1// Copyright (C) 2017 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Marc Mutz <marc.mutz@kdab.com>
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qstringview.h"
5
6QT_BEGIN_NAMESPACE
7
8/*!
9 \class QStringView
10 \inmodule QtCore
11 \since 5.10
12 \brief The QStringView class provides a unified view on UTF-16 strings with a read-only subset of the QString API.
13 \reentrant
14 \ingroup tools
15 \ingroup string-processing
16
17 A QStringView references a contiguous portion of a UTF-16 string it does
18 not own. It acts as an interface type to all kinds of UTF-16 string,
19 without the need to construct a QString first.
20
21 The UTF-16 string may be represented as an array (or an array-compatible
22 data-structure such as QString,
23 std::basic_string, etc.) of QChar, \c ushort, \c char16_t or
24 (on platforms, such as Windows, where it is a 16-bit type) \c wchar_t.
25
26 QStringView is designed as an interface type; its main use-case is
27 as a function parameter type. When QStringViews are used as automatic
28 variables or data members, care must be taken to ensure that the referenced
29 string data (for example, owned by a QString) outlives the QStringView on all code paths,
30 lest the string view ends up referencing deleted data.
31
32 When used as an interface type, QStringView allows a single function to accept
33 a wide variety of UTF-16 string data sources. One function accepting QStringView
34 thus replaces three function overloads (taking QString and
35 \c{(const QChar*, qsizetype)}), while at the same time enabling even more string data
36 sources to be passed to the function, such as \c{u"Hello World"}, a \c char16_t
37 string literal.
38
39 QStringViews should be passed by value, not by reference-to-const:
40 \snippet code/src_corelib_text_qstringview.cpp 0
41
42 If you want to give your users maximum freedom in what strings they can pass
43 to your function, accompany the QStringView overload with overloads for
44
45 \list
46 \li \e QChar: this overload can delegate to the QStringView version:
47 \snippet code/src_corelib_text_qstringview.cpp 1
48 even though, for technical reasons, QStringView cannot provide a
49 QChar constructor by itself.
50 \li \e QString: if you store an unmodified copy of the string and thus would
51 like to take advantage of QString's implicit sharing.
52 \li QLatin1StringView: if you can implement the function without converting the
53 QLatin1StringView to UTF-16 first; users expect a function overloaded on
54 QLatin1StringView to perform strictly less memory allocations than the
55 semantically equivalent call of the QStringView version, involving
56 construction of a QString from the QLatin1StringView.
57 \endlist
58
59 QStringView can also be used as the return value of a function. If you call a
60 function returning QStringView, take extra care to not keep the QStringView
61 around longer than the function promises to keep the referenced string data alive.
62 If in doubt, obtain a strong reference to the data by calling toString() to convert
63 the QStringView into a QString.
64
65 QStringView is a \e{Literal Type}, but since it stores data as \c{char16_t}, iteration
66 is not \c constexpr (casts from \c{const char16_t*} to \c{const QChar*}, which is not
67 allowed in \c constexpr functions). You can use an indexed loop and/or utf16() in
68 \c constexpr contexts instead.
69
70 \sa QString
71*/
72
73/*!
74 \typedef QStringView::storage_type
75
76 Alias for \c{char16_t}.
77*/
78
79/*!
80 \typedef QStringView::value_type
81
82 Alias for \c{const QChar}. Provided for compatibility with the STL.
83*/
84
85/*!
86 \typedef QStringView::difference_type
87
88 Alias for \c{std::ptrdiff_t}. Provided for compatibility with the STL.
89*/
90
91/*!
92 \typedef QStringView::size_type
93
94 Alias for qsizetype. Provided for compatibility with the STL.
95*/
96
97/*!
98 \typedef QStringView::reference
99
100 Alias for \c{value_type &}. Provided for compatibility with the STL.
101
102 QStringView does not support mutable references, so this is the same
103 as const_reference.
104*/
105
106/*!
107 \typedef QStringView::const_reference
108
109 Alias for \c{value_type &}. Provided for compatibility with the STL.
110*/
111
112/*!
113 \typedef QStringView::pointer
114
115 Alias for \c{value_type *}. Provided for compatibility with the STL.
116
117 QStringView does not support mutable pointers, so this is the same
118 as const_pointer.
119*/
120
121/*!
122 \typedef QStringView::const_pointer
123
124 Alias for \c{value_type *}. Provided for compatibility with the STL.
125*/
126
127/*!
128 \typedef QStringView::iterator
129
130 This typedef provides an STL-style const iterator for QStringView.
131
132 QStringView does not support mutable iterators, so this is the same
133 as const_iterator.
134
135 \sa const_iterator, reverse_iterator
136*/
137
138/*!
139 \typedef QStringView::const_iterator
140
141 This typedef provides an STL-style const iterator for QStringView.
142
143 \sa iterator, const_reverse_iterator
144*/
145
146/*!
147 \typedef QStringView::reverse_iterator
148
149 This typedef provides an STL-style const reverse iterator for QStringView.
150
151 QStringView does not support mutable reverse iterators, so this is the
152 same as const_reverse_iterator.
153
154 \sa const_reverse_iterator, iterator
155*/
156
157/*!
158 \typedef QStringView::const_reverse_iterator
159
160 This typedef provides an STL-style const reverse iterator for QStringView.
161
162 \sa reverse_iterator, const_iterator
163*/
164
165/*!
166 \fn QStringView::QStringView()
167
168 Constructs a null string view.
169
170 \sa isNull()
171*/
172
173/*!
174 \fn QStringView::QStringView(std::nullptr_t)
175
176 Constructs a null string view.
177
178 \sa isNull()
179*/
180
181/*!
182 \fn template <typename Char> QStringView::QStringView(const Char *str, qsizetype len)
183
184 Constructs a string view on \a str with length \a len.
185
186 The range \c{[str,len)} must remain valid for the lifetime of this string view object.
187
188 Passing \nullptr as \a str is safe if \a len is 0, too, and results in a null string view.
189
190 The behavior is undefined if \a len is negative or, when positive, if \a str is \nullptr.
191
192 This constructor only participates in overload resolution if \c Char is a compatible
193 character type. The compatible character types are: \c QChar, \c ushort, \c char16_t and
194 (on platforms, such as Windows, where it is a 16-bit type) \c wchar_t.
195*/
196
197/*!
198 \fn template <typename Char> QStringView::QStringView(const Char *first, const Char *last)
199
200 Constructs a string view on \a first with length (\a last - \a first).
201
202 The range \c{[first,last)} must remain valid for the lifetime of
203 this string view object.
204
205 Passing \c \nullptr as \a first is safe if \a last is \nullptr, too,
206 and results in a null string view.
207
208 The behavior is undefined if \a last precedes \a first, or \a first
209 is \nullptr and \a last is not.
210
211 This constructor only participates in overload resolution if \c Char
212 is a compatible character type. The compatible character types
213 are: \c QChar, \c ushort, \c char16_t and (on platforms, such as
214 Windows, where it is a 16-bit type) \c wchar_t.
215*/
216
217/*!
218 \fn template <typename Char> QStringView::QStringView(const Char *str)
219
220 Constructs a string view on \a str. The length is determined
221 by scanning for the first \c{Char(0)}.
222
223 \a str must remain valid for the lifetime of this string view object.
224
225 Passing \nullptr as \a str is safe and results in a null string view.
226
227 This constructor only participates in overload resolution if \a
228 str is not an array and if \c Char is a compatible character
229 type. The compatible character types are: \c QChar, \c ushort, \c
230 char16_t and (on platforms, such as Windows, where it is a 16-bit
231 type) \c wchar_t.
232*/
233
234/*!
235 \fn template <typename Char, size_t N> QStringView::QStringView(const Char (&string)[N])
236
237 Constructs a string view on the character string literal \a string.
238 The view covers the array until the first \c{Char(0)} is encountered,
239 or \c N, whichever comes first.
240 If you need the full array, use fromArray() instead.
241
242 \a string must remain valid for the lifetime of this string view
243 object.
244
245 This constructor only participates in overload resolution if \a
246 string is an actual array and \c Char is a compatible character
247 type. The compatible character types are: \c QChar, \c ushort, \c
248 char16_t and (on platforms, such as Windows, where it is a 16-bit
249 type) \c wchar_t.
250
251 \sa fromArray
252*/
253
254/*!
255 \fn QStringView::QStringView(const QString &str)
256
257 Constructs a string view on \a str.
258
259 \c{str.data()} must remain valid for the lifetime of this string view object.
260
261 The string view will be null if and only if \c{str.isNull()}.
262*/
263
264/*!
265 \fn template <typename Container, if_compatible_container<Container>> QStringView::QStringView(const Container &str)
266
267 Constructs a string view on \a str. The length is taken from \c{std::size(str)}.
268
269 \c{std::data(str)} must remain valid for the lifetime of this string view object.
270
271 This constructor only participates in overload resolution if \c Container is a
272 container with a compatible character type as \c{value_type}. The
273 compatible character types are: \c QChar, \c ushort, \c char16_t and
274 (on platforms, such as Windows, where it is a 16-bit type) \c wchar_t.
275
276 The string view will be empty if and only if \c{std::size(str) == 0}. It is unspecified
277 whether this constructor can result in a null string view (\c{std::data(str)} would
278 have to return \nullptr for this).
279
280 \sa isNull(), isEmpty()
281*/
282
283/*!
284 \fn template <typename Char, size_t Size> static QStringView QStringView::fromArray(const Char (&string)[Size]) noexcept
285
286 Constructs a string view on the full character string literal \a string,
287 including any trailing \c{Char(0)}. If you don't want the
288 null-terminator included in the view then you can chop() it off
289 when you are certain it is at the end. Alternatively you can use
290 the constructor overload taking an array literal which will create
291 a view up to, but not including, the first null-terminator in the data.
292
293 \a string must remain valid for the lifetime of this string view
294 object.
295
296 This function will work with any array literal if \c Char is a
297 compatible character type. The compatible character types are: \c QChar, \c ushort, \c
298 char16_t and (on platforms, such as Windows, where it is a 16-bit
299 type) \c wchar_t.
300*/
301
302/*!
303 \fn QString QStringView::toString() const
304
305 Returns a deep copy of this string view's data as a QString.
306
307 The return value will be the null QString if and only if this string view is null.
308*/
309
310/*!
311 \fn const QChar *QStringView::data() const
312
313//! [const-pointer-to-first-ch]
314 Returns a const pointer to the first character in the string view.
315
316 \note The character array represented by the return value is \e not null-terminated.
317//! [const-pointer-to-first-ch]
318
319 \sa begin(), end(), utf16()
320*/
321
322/*!
323 \fn const QChar *QStringView::constData() const
324 \since 6.0
325
326 \include qstringview.cpp const-pointer-to-first-ch
327
328 \sa data(), begin(), end(), utf16()
329*/
330
331/*!
332 \fn const storage_type *QStringView::utf16() const
333
334 \include qstringview.cpp const-pointer-to-first-ch
335
336 \c{storage_type} is \c{char16_t}.
337
338 \sa begin(), end(), data()
339*/
340
341/*!
342 \fn QStringView::const_iterator QStringView::begin() const
343
344 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first character in
345 the string view.
346
347 This function is provided for STL compatibility.
348
349 \sa end(), constBegin(), cbegin(), rbegin(), data()
350*/
351
352/*!
353 \fn QStringView::const_iterator QStringView::cbegin() const
354
355 Same as begin().
356
357 This function is provided for STL compatibility.
358
359 \sa cend(), begin(), constBegin(), crbegin(), data()
360*/
361
362/*!
363 \fn QStringView::const_iterator QStringView::constBegin() const
364 \since 6.1
365
366 Same as begin().
367
368 \sa constEnd(), begin(), cbegin(), crbegin(), data()
369*/
370
371/*!
372 \fn QStringView::const_iterator QStringView::end() const
373
374 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
375 character after the last character in the list.
376
377 This function is provided for STL compatibility.
378
379 \sa begin(), constEnd(), cend(), rend()
380*/
381
382/*! \fn QStringView::const_iterator QStringView::cend() const
383
384 Same as end().
385
386 This function is provided for STL compatibility.
387
388 \sa cbegin(), end(), constEnd(), crend()
389*/
390
391/*! \fn QStringView::const_iterator QStringView::constEnd() const
392 \since 6.1
393
394 Same as end().
395
396 \sa constBegin(), end(), cend(), crend()
397*/
398
399/*!
400 \fn QStringView::const_reverse_iterator QStringView::rbegin() const
401
402 Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing to the first
403 character in the string view, in reverse order.
404
405 This function is provided for STL compatibility.
406
407 \sa rend(), crbegin(), begin()
408*/
409
410/*!
411 \fn QStringView::const_reverse_iterator QStringView::crbegin() const
412
413 Same as rbegin().
414
415 This function is provided for STL compatibility.
416
417 \sa crend(), rbegin(), cbegin()
418*/
419
420/*!
421 \fn QStringView::const_reverse_iterator QStringView::rend() const
422
423 Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to one past
424 the last character in the string view, in reverse order.
425
426 This function is provided for STL compatibility.
427
428 \sa rbegin(), crend(), end()
429*/
430
431/*!
432 \fn QStringView::const_reverse_iterator QStringView::crend() const
433
434 Same as rend().
435
436 This function is provided for STL compatibility.
437
438 \sa crbegin(), rend(), cend()
439*/
440
441/*!
442 \fn bool QStringView::empty() const
443
444 Returns whether this string view is empty - that is, whether \c{size() == 0}.
445
446 This function is provided for STL compatibility.
447
448 \sa isEmpty(), isNull(), size(), length()
449*/
450
451/*!
452 \fn bool QStringView::isEmpty() const
453
454 Returns whether this string view is empty - that is, whether \c{size() == 0}.
455
456 This function is provided for compatibility with other Qt containers.
457
458 \sa empty(), isNull(), size(), length()
459*/
460
461/*!
462 \fn bool QStringView::isNull() const
463
464 Returns whether this string view is null - that is, whether \c{data() == nullptr}.
465
466 This functions is provided for compatibility with other Qt containers.
467
468 \sa empty(), isEmpty(), size(), length()
469*/
470
471/*!
472 \fn qsizetype QStringView::size() const
473
474 Returns the size of this string view, in UTF-16 code units (that is,
475 surrogate pairs count as two for the purposes of this function, the same
476 as in QString).
477
478 \sa empty(), isEmpty(), isNull(), length()
479*/
480
481/*!
482 \fn QStringView::length() const
483
484 Same as size().
485
486 This function is provided for compatibility with other Qt containers.
487
488 \sa empty(), isEmpty(), isNull(), size()
489*/
490
491/*!
492 \fn QChar QStringView::operator[](qsizetype n) const
493
494 Returns the character at position \a n in this string view.
495
496 The behavior is undefined if \a n is negative or not less than size().
497
498 \sa at(), front(), back()
499*/
500
501/*!
502 \fn QChar QStringView::at(qsizetype n) const
503
504 Returns the character at position \a n in this string view.
505
506 The behavior is undefined if \a n is negative or not less than size().
507
508 \sa operator[](), front(), back()
509*/
510
511/*!
512 \fn template <typename...Args> QString QStringView::arg(Args &&...args) const
513 \fn template <typename...Args> QString QLatin1StringView::arg(Args &&...args) const
514 \fn template <typename...Args> QString QString::arg(Args &&...args) const
515 \since 5.14
516
517 Replaces occurrences of \c{%N} in this string with the corresponding
518 argument from \a args. The arguments are not positional: the first of
519 the \a args replaces the \c{%N} with the lowest \c{N} (all of them), the
520 second of the \a args the \c{%N} with the next-lowest \c{N} etc.
521
522 \c Args can consist of anything that implicitly converts to QString,
523 QStringView or QLatin1StringView.
524
525 In addition, the following types are also supported: QChar, QLatin1Char.
526
527 \sa QString::arg()
528*/
529
530/*!
531 \fn QChar QStringView::front() const
532
533 Returns the first character in the string view. Same as first().
534
535 This function is provided for STL compatibility.
536
537//! [calling-on-empty-is-UB]
538 \warning Calling this function on an empty string view constitutes
539 undefined behavior.
540//! [calling-on-empty-is-UB]
541
542 \sa back(), first(), last()
543*/
544
545/*!
546 \fn QChar QStringView::back() const
547
548 Returns the last character in the string view. Same as last().
549
550 This function is provided for STL compatibility.
551
552 \include qstringview.cpp calling-on-empty-is-UB
553
554 \sa front(), first(), last()
555*/
556
557/*!
558 \fn QChar QStringView::first() const
559
560 Returns the first character in the string view. Same as front().
561
562 This function is provided for compatibility with other Qt containers.
563
564 \include qstringview.cpp calling-on-empty-is-UB
565
566 \sa front(), back(), last()
567*/
568
569/*!
570 \fn QChar QStringView::last() const
571
572 Returns the last character in the string view. Same as back().
573
574 This function is provided for compatibility with other Qt containers.
575
576 \include qstringview.cpp calling-on-empty-is-UB
577
578 \sa back(), front(), first()
579*/
580
581/*!
582 \fn QStringView QStringView::mid(qsizetype start, qsizetype length) const
583
584 Returns the substring of length \a length starting at position
585 \a start in this object.
586
587 \deprecated Use sliced() instead in new code.
588
589 Returns an empty string view if \a start exceeds the
590 length of the string view. If there are less than \a length characters
591 available in the string view starting at \a start, or if
592 \a length is negative (default), the function returns all characters that
593 are available from \a start.
594
595 \sa first(), last(), sliced(), chopped(), chop(), truncate()
596*/
597
598/*!
599 \fn QStringView QStringView::left(qsizetype length) const
600
601 \deprecated Use first() instead in new code.
602
603 Returns the substring of length \a length starting at position
604 0 in this object.
605
606 The entire string view is returned if \a length is greater than or equal
607 to size(), or less than zero.
608
609 \sa first(), last(), sliced(), startsWith(), chopped(), chop(), truncate()
610*/
611
612/*!
613 \fn QStringView QStringView::right(qsizetype length) const
614
615 \deprecated Use last() instead in new code.
616
617 Returns the substring of length \a length starting at position
618 size() - \a length in this object.
619
620 The entire string view is returned if \a length is greater than or equal
621 to size(), or less than zero.
622
623 \sa first(), last(), sliced(), endsWith(), chopped(), chop(), truncate()
624*/
625
626/*!
627 \fn QStringView QStringView::first(qsizetype n) const
628 \since 6.0
629
630 Returns a string view that points to the first \a n characters
631 of this string view.
632
633 \note The behavior is undefined when \a n < 0 or \a n > size().
634
635 \sa last(), sliced(), startsWith(), chopped(), chop(), truncate()
636*/
637
638/*!
639 \fn QStringView QStringView::last(qsizetype n) const
640 \since 6.0
641
642 Returns a string view that points to the last \a n characters of this string
643 view.
644
645 \note The behavior is undefined when \a n < 0 or \a n > size().
646
647 \sa first(), sliced(), endsWith(), chopped(), chop(), truncate()
648*/
649
650/*!
651 \fn QStringView QStringView::sliced(qsizetype pos, qsizetype n) const
652 \since 6.0
653
654 Returns a string view that points to \a n characters of this string view,
655 starting at position \a pos.
656
657 \note The behavior is undefined when \a pos < 0, \a n < 0,
658 or \a pos + \a n > size().
659
660 \sa first(), last(), chopped(), chop(), truncate()
661*/
662
663/*!
664 \fn QStringView QStringView::sliced(qsizetype pos) const
665 \since 6.0
666 \overload
667
668 Returns a string view starting at position \a pos in this object,
669 and extending to its end.
670
671 \note The behavior is undefined when \a pos < 0 or \a pos > size().
672
673 \sa first(), last(), chopped(), chop(), truncate()
674*/
675
676/*!
677 \fn QStringView QStringView::chopped(qsizetype length) const
678
679 Returns the substring of length size() - \a length starting at the
680 beginning of this object.
681
682 Same as \c{left(size() - length)}.
683
684 \note The behavior is undefined when \a length < 0 or \a length > size().
685
686 \sa mid(), left(), right(), chop(), truncate()
687*/
688
689/*!
690 \fn void QStringView::truncate(qsizetype length)
691
692 Truncates this string view to length \a length.
693
694 Same as \c{*this = left(length)}.
695
696 \note The behavior is undefined when \a length < 0 or \a length > size().
697
698 \sa mid(), left(), right(), chopped(), chop()
699*/
700
701/*!
702 \fn void QStringView::chop(qsizetype length)
703
704 Truncates this string view by \a length characters.
705
706 Same as \c{*this = left(size() - length)}.
707
708 \note The behavior is undefined when \a length < 0 or \a length > size().
709
710 \sa mid(), left(), right(), chopped(), truncate()
711*/
712
713/*!
714 \fn QStringView QStringView::trimmed() const
715
716 Strips leading and trailing whitespace and returns the result.
717
718 Whitespace means any character for which QChar::isSpace() returns
719 \c true. This includes the ASCII characters '\\t', '\\n', '\\v',
720 '\\f', '\\r', and ' '.
721*/
722
723/*!
724 \fn int QStringView::compare(QStringView str, Qt::CaseSensitivity cs) const
725 \since 5.12
726
727 Returns an integer that compares to zero as this string view compares to the
728 string view \a str.
729
730 \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison}
731
732 \sa operator==(), operator<(), operator>()
733*/
734
735/*!
736 \fn int QStringView::compare(QUtf8StringView str, Qt::CaseSensitivity cs) const
737 \since 6.5
738
739 Returns an integer that compares to zero as this string view compares to the
740 string view \a str.
741
742 \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison}
743
744 \sa operator==(), operator<(), operator>()
745*/
746
747/*!
748 \fn int QStringView::compare(QLatin1StringView l1, Qt::CaseSensitivity cs) const
749 \fn int QStringView::compare(QChar ch) const
750 \fn int QStringView::compare(QChar ch, Qt::CaseSensitivity cs) const
751 \since 5.15
752
753 Returns an integer that compares to zero as this string view compares to the
754 Latin-1 string viewed by \a l1, or the character \a ch, respectively.
755
756 \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison}
757
758 \sa operator==(), operator<(), operator>()
759*/
760
761/*!
762 \fn QStringView::operator==(QStringView lhs, QStringView rhs)
763 \fn QStringView::operator!=(QStringView lhs, QStringView rhs)
764 \fn QStringView::operator< (QStringView lhs, QStringView rhs)
765 \fn QStringView::operator<=(QStringView lhs, QStringView rhs)
766 \fn QStringView::operator> (QStringView lhs, QStringView rhs)
767 \fn QStringView::operator>=(QStringView lhs, QStringView rhs)
768
769 Operators for comparing \a lhs to \a rhs.
770
771 \sa compare()
772*/
773
774/*!
775 \fn int QStringView::localeAwareCompare(QStringView other) const
776 \since 6.4
777
778 Compares this string view with the \a other string view and returns
779 an integer less than, equal to, or greater than zero if this string
780 view is less than, equal to, or greater than the \a other string view.
781
782 The comparison is performed in a locale- and also platform-dependent
783 manner. Use this function to present sorted lists of strings to the
784 user.
785
786 \sa {Comparing Strings}
787*/
788
789/*
790//! [utf16-or-latin1-or-ch]
791the UTF-16 string viewed by \a str, the Latin-1 string viewed by \a l1,
792or the character \a ch
793//! [utf16-or-latin1-or-ch]
794*/
795
796/*!
797 \fn bool QStringView::startsWith(QStringView str, Qt::CaseSensitivity cs) const
798 \fn bool QStringView::startsWith(QLatin1StringView l1, Qt::CaseSensitivity cs) const
799 \fn bool QStringView::startsWith(QChar ch) const
800 \fn bool QStringView::startsWith(QChar ch, Qt::CaseSensitivity cs) const
801
802 Returns \c true if this string view starts with
803 \include qstringview.cpp utf16-or-latin1-or-ch
804 respectively; otherwise returns \c false.
805
806 \include qstring.qdocinc {search-comparison-case-sensitivity} {search}
807
808 \sa endsWith()
809*/
810
811/*!
812 \fn bool QStringView::endsWith(QStringView str, Qt::CaseSensitivity cs) const
813 \fn bool QStringView::endsWith(QLatin1StringView l1, Qt::CaseSensitivity cs) const
814 \fn bool QStringView::endsWith(QChar ch) const
815 \fn bool QStringView::endsWith(QChar ch, Qt::CaseSensitivity cs) const
816
817 Returns \c true if this string view ends with
818 \include qstringview.cpp utf16-or-latin1-or-ch
819 respectively; otherwise returns \c false.
820
821 \include qstring.qdocinc {search-comparison-case-sensitivity} {search}
822
823 \sa startsWith()
824*/
825
826/*!
827 \fn qsizetype QStringView::indexOf(QStringView str, qsizetype from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
828 \fn qsizetype QStringView::indexOf(QLatin1StringView l1, qsizetype from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
829 \fn qsizetype QStringView::indexOf(QChar c, qsizetype from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
830 \since 5.14
831
832 Returns the index position of the first occurrence of
833 \include qstringview.cpp utf16-or-latin1-or-ch
834 respectively, in this string view, searching forward from index position
835 \a from. Returns -1 if \a str, \a l1 or \a ch is not found, respectively.
836
837 \include qstring.qdocinc {search-comparison-case-sensitivity} {search}
838
839 \include qstring.qdocinc negative-index-start-search-from-end
840
841 \sa QString::indexOf()
842*/
843
844/*!
845 \fn bool QStringView::contains(QStringView str, Qt::CaseSensitivity cs) const
846 \fn bool QStringView::contains(QLatin1StringView l1, Qt::CaseSensitivity cs) const
847 \fn bool QStringView::contains(QChar c, Qt::CaseSensitivity cs) const
848 \since 5.14
849
850 Returns \c true if this string view contains an occurrence of
851 \include qstringview.cpp utf16-or-latin1-or-ch
852 respectively; otherwise returns \c false.
853
854 \include qstring.qdocinc {search-comparison-case-sensitivity} {search}
855
856 \sa indexOf()
857*/
858
859/*!
860 \fn qsizetype QStringView::lastIndexOf(QStringView str, qsizetype from, Qt::CaseSensitivity cs) const
861 \fn qsizetype QStringView::lastIndexOf(QLatin1StringView l1, qsizetype from, Qt::CaseSensitivity cs) const
862 \fn qsizetype QStringView::lastIndexOf(QChar c, qsizetype from, Qt::CaseSensitivity cs) const
863 \since 5.14
864
865 Returns the index position of the last occurrence of
866 \include qstringview.cpp utf16-or-latin1-or-ch
867 respectively, in this string view, searching backward from index
868 position \a from.
869
870 \include qstring.qdocinc negative-index-start-search-from-end
871
872 Returns -1 if \a str, \a l1 or \a c is not found, respectively.
873
874 \include qstring.qdocinc {search-comparison-case-sensitivity} {search}
875
876 \note When searching for a 0-length \a str or \a l1, the match at
877 the end of the data is excluded from the search by a negative \a
878 from, even though \c{-1} is normally thought of as searching from
879 the end of the string view: the match at the end is \e after the
880 last character, so it is excluded. To include such a final empty
881 match, either give a positive value for \a from or omit the \a from
882 parameter entirely.
883
884 \sa QString::lastIndexOf()
885*/
886
887/*!
888 \fn qsizetype QStringView::lastIndexOf(QStringView str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
889 \fn qsizetype QStringView::lastIndexOf(QLatin1StringView l1, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
890 \since 6.2
891 \overload lastIndexOf()
892
893 Returns the index position of the last occurrence of the UTF-16 string viewed
894 by \a str or the Latin-1 string viewed by \a l1 respectively, in this string
895 view searching backward from the last character of this string view. Returns
896 -1 if \a str or \a l1 is not found, respectively.
897
898 \include qstring.qdocinc {search-comparison-case-sensitivity} {search}
899
900 \sa QString::lastIndexOf()
901*/
902
903/*!
904 \fn QStringView::lastIndexOf(QChar c, Qt::CaseSensitivity cs) const
905 \since 6.3
906 \overload lastIndexOf()
907*/
908
909#if QT_CONFIG(regularexpression)
910/*!
911 \fn qsizetype QStringView::indexOf(const QRegularExpression &re, qsizetype from, QRegularExpressionMatch *rmatch) const
912 \since 6.1
913
914 Returns the index position of the first match of the regular
915 expression \a re in the string view, searching forward from index
916 position \a from. Returns -1 if \a re didn't match anywhere.
917
918 If the match is successful and \a rmatch is not \nullptr, it also
919 writes the results of the match into the QRegularExpressionMatch object
920 pointed to by \a rmatch.
921
922 \note Due to how the regular expression matching algorithm works,
923 this function will actually match repeatedly from the beginning of
924 the string view until the position \a from is reached.
925*/
926
927/*!
928 \fn qsizetype QStringView::lastIndexOf(const QRegularExpression &re, qsizetype from, QRegularExpressionMatch *rmatch) const
929 \since 6.1
930
931 Returns the index position of the last match of the regular
932 expression \a re in the string view, which starts before the index
933 position \a from.
934
935 \include qstring.qdocinc negative-index-start-search-from-end
936
937 Returns -1 if \a re didn't match anywhere.
938
939 If the match is successful and \a rmatch is not \nullptr, it also
940 writes the results of the match into the QRegularExpressionMatch object
941 pointed to by \a rmatch.
942
943 \note Due to how the regular expression matching algorithm works,
944 this function will actually match repeatedly from the beginning of
945 the string view until the position \a from is reached.
946
947 \note When searching for a regular expression \a re that may match
948 0 characters, the match at the end of the data is excluded from the
949 search by a negative \a from, even though \c{-1} is normally
950 thought of as searching from the end of the string view: the match
951 at the end is \e after the last character, so it is excluded. To
952 include such a final empty match, either give a positive value for
953 \a from or omit the \a from parameter entirely.
954*/
955
956/*!
957 \fn qsizetype QStringView::lastIndexOf(const QRegularExpression &re, QRegularExpressionMatch *rmatch = nullptr) const
958 \since 6.2
959
960 Returns the index position of the last match of the regular
961 expression \a re in the string view. Returns -1 if \a re didn't match
962 anywhere.
963
964 If the match is successful and \a rmatch is not \nullptr, it also
965 writes the results of the match into the QRegularExpressionMatch object
966 pointed to by \a rmatch.
967
968 \note Due to how the regular expression matching algorithm works,
969 this function will actually match repeatedly from the beginning of
970 the string view until the end of the string view is reached.
971*/
972
973/*!
974 \fn bool QStringView::contains(const QRegularExpression &re, QRegularExpressionMatch *rmatch) const
975 \since 6.1
976
977 Returns \c true if the regular expression \a re matches somewhere in this
978 string view; otherwise returns \c false.
979
980 If the match is successful and \a rmatch is not \nullptr, it also
981 writes the results of the match into the QRegularExpressionMatch object
982 pointed to by \a rmatch.
983
984 \sa QRegularExpression::match()
985*/
986
987/*!
988 \fn qsizetype QStringView::count(const QRegularExpression &re) const
989 \since 6.1
990
991 Returns the number of times the regular expression \a re matches
992 in the string view.
993
994 For historical reasons, this function counts overlapping matches.
995 This behavior is different from simply iterating over the matches
996 in the string view using QRegularExpressionMatchIterator.
997
998 \sa QRegularExpression::globalMatch()
999
1000*/
1001#endif // QT_CONFIG(regularexpression)
1002
1003/*!
1004 \fn QByteArray QStringView::toLatin1() const
1005
1006 Returns a Latin-1 representation of the string as a QByteArray.
1007
1008 The behavior is undefined if the string contains non-Latin1 characters.
1009
1010 \sa toUtf8(), toLocal8Bit(), QStringEncoder
1011*/
1012
1013/*!
1014 \fn QByteArray QStringView::toLocal8Bit() const
1015
1016 Returns a local 8-bit representation of the string as a QByteArray.
1017
1018 On Unix systems this is equivalen to toUtf8(), on Windows the systems
1019 current code page is being used.
1020
1021 The behavior is undefined if the string contains characters not
1022 supported by the locale's 8-bit encoding.
1023
1024 \sa toLatin1(), toUtf8(), QStringEncoder
1025*/
1026
1027/*!
1028 \fn QByteArray QStringView::toUtf8() const
1029
1030 Returns a UTF-8 representation of the string view as a QByteArray.
1031
1032 UTF-8 is a Unicode codec and can represent all characters in a Unicode
1033 string like QString.
1034
1035 \sa toLatin1(), toLocal8Bit(), QStringEncoder
1036*/
1037
1038/*!
1039 \fn QList<uint> QStringView::toUcs4() const
1040
1041 Returns a UCS-4/UTF-32 representation of the string view as a QList<uint>.
1042
1043 UCS-4 is a Unicode codec and therefore it is lossless. All characters from
1044 this string view will be encoded in UCS-4. Any invalid sequence of code units in
1045 this string view is replaced by the Unicode replacement character
1046 (QChar::ReplacementCharacter, which corresponds to \c{U+FFFD}).
1047
1048 The returned list is not 0-terminated.
1049
1050 \sa toUtf8(), toLatin1(), toLocal8Bit(), QStringEncoder
1051*/
1052
1053/*!
1054 \fn template <typename QStringLike> qToStringViewIgnoringNull(const QStringLike &s);
1055 \since 5.10
1056 \internal
1057
1058 Convert \a s to a QStringView ignoring \c{s.isNull()}.
1059
1060 Returns a string view that references \a{s}' data, but is never null.
1061
1062 This is a faster way to convert a QString to a QStringView,
1063 if null QStrings can legitimately be treated as empty ones.
1064
1065 \sa QString::isNull(), QStringView
1066*/
1067
1068/*!
1069 \fn bool QStringView::isRightToLeft() const
1070 \since 5.11
1071
1072 Returns \c true if the string view is read right to left.
1073
1074 \sa QString::isRightToLeft()
1075*/
1076
1077/*!
1078 \fn bool QStringView::isValidUtf16() const
1079 \since 5.15
1080
1081 Returns \c true if the string view contains valid UTF-16 encoded data,
1082 or \c false otherwise.
1083
1084 Note that this function does not perform any special validation of the
1085 data; it merely checks if it can be successfully decoded from UTF-16.
1086 The data is assumed to be in host byte order; the presence of a BOM
1087 is meaningless.
1088
1089 \sa QString::isValidUtf16()
1090*/
1091
1092/*!
1093 \fn QStringView::toWCharArray(wchar_t *array) const
1094 \since 5.14
1095
1096 Transcribes this string view into the given \a array.
1097
1098 The caller is responsible for ensuring \a array is large enough to hold the
1099 \c wchar_t encoding of this string view (allocating the array with the same length
1100 as the string view is always sufficient). The array is encoded in UTF-16 on
1101 platforms where \c wchar_t is 2 bytes wide (e.g. Windows); otherwise (Unix
1102 systems), \c wchar_t is assumed to be 4 bytes wide and the data is written
1103 in UCS-4.
1104
1105 \note This function writes no null terminator to the end of \a array.
1106
1107 Returns the number of \c wchar_t entries written to \a array.
1108
1109 \sa QString::toWCharArray()
1110*/
1111
1112/*!
1113 \fn qsizetype QStringView::count(QChar ch, Qt::CaseSensitivity cs) const noexcept
1114
1115 \since 6.0
1116 \overload count()
1117
1118 Returns the number of occurrences of the character \a ch in the
1119 string view.
1120
1121 \include qstring.qdocinc {search-comparison-case-sensitivity} {search}
1122
1123 \sa QString::count(), contains(), indexOf()
1124*/
1125
1126/*!
1127 \fn qsizetype QStringView::count(QStringView str, Qt::CaseSensitivity cs) const noexcept
1128
1129 \since 6.0
1130 \overload count()
1131
1132 Returns the number of (potentially overlapping) occurrences of the
1133 string view \a str in this string view.
1134
1135 \include qstring.qdocinc {search-comparison-case-sensitivity} {search}
1136
1137 \sa QString::count(), contains(), indexOf()
1138*/
1139
1140/*!
1141 \fn qsizetype QStringView::count(QLatin1StringView l1, Qt::CaseSensitivity cs) const noexcept
1142
1143 \since 6.4
1144 \overload count()
1145
1146 Returns the number of (potentially overlapping) occurrences of the
1147 Latin-1 string viewed by \a l1 in this string view.
1148
1149 \include qstring.qdocinc {search-comparison-case-sensitivity} {search}
1150
1151 \sa QString::count(), contains(), indexOf()
1152*/
1153
1154/*!
1155 \fn qint64 QStringView::toLongLong(bool *ok, int base) const
1156
1157 Returns the string view converted to a \c{long long} using base \a
1158 base, which is 10 by default and must be between 2 and 36, or 0.
1159 Returns 0 if the conversion fails.
1160
1161 If \a ok is not \nullptr, failure is reported by setting *\a{ok}
1162 to \c false, and success by setting *\a{ok} to \c true.
1163
1164 If \a base is 0, the C language convention is used: if the string view
1165 begins with "0x", base 16 is used; otherwise, if the string view begins with "0",
1166 base 8 is used; otherwise, base 10 is used.
1167
1168 The string conversion will always happen in the 'C' locale. For locale
1169 dependent conversion use QLocale::toLongLong()
1170
1171 \sa QString::toLongLong()
1172
1173 \since 6.0
1174*/
1175
1176/*!
1177 \fn quint64 QStringView::toULongLong(bool *ok, int base) const
1178
1179 Returns the string view converted to an \c{unsigned long long} using base \a
1180 base, which is 10 by default and must be between 2 and 36, or 0.
1181 Returns 0 if the conversion fails.
1182
1183 If \a ok is not \nullptr, failure is reported by setting *\a{ok}
1184 to \c false, and success by setting *\a{ok} to \c true.
1185
1186 If \a base is 0, the C language convention is used: if the string view
1187 begins with "0x", base 16 is used; otherwise, if the string view begins with "0",
1188 base 8 is used; otherwise, base 10 is used.
1189
1190 The string conversion will always happen in the 'C' locale. For locale
1191 dependent conversion use QLocale::toULongLong()
1192
1193 \sa QString::toULongLong()
1194
1195 \since 6.0
1196*/
1197
1198/*!
1199 \fn long QStringView::toLong(bool *ok, int base) const
1200
1201 Returns the string view converted to a \c long using base \a
1202 base, which is 10 by default and must be between 2 and 36, or 0.
1203 Returns 0 if the conversion fails.
1204
1205 If \a ok is not \nullptr, failure is reported by setting *\a{ok}
1206 to \c false, and success by setting *\a{ok} to \c true.
1207
1208 If \a base is 0, the C language convention is used: if the string view
1209 begins with "0x", base 16 is used; otherwise, if the string view begins with "0",
1210 base 8 is used; otherwise, base 10 is used.
1211
1212 The string conversion will always happen in the 'C' locale. For locale
1213 dependent conversion use QLocale::toLong()
1214
1215 \sa QString::toLong()
1216
1217 \since 6.0
1218*/
1219
1220/*!
1221 \fn ulong QStringView::toULong(bool *ok, int base) const
1222
1223 Returns the string view converted to an \c{unsigned long} using base \a
1224 base, which is 10 by default and must be between 2 and 36, or 0.
1225 Returns 0 if the conversion fails.
1226
1227 If \a ok is not \nullptr, failure is reported by setting *\a{ok}
1228 to \c false, and success by setting *\a{ok} to \c true.
1229
1230 If \a base is 0, the C language convention is used: if the string view
1231 begins with "0x", base 16 is used; otherwise, if the string view begins with "0",
1232 base 8 is used; otherwise, base 10 is used.
1233
1234 The string conversion will always happen in the 'C' locale. For locale
1235 dependent conversion use QLocale::toULongLong()
1236
1237 \sa QString::toULong()
1238
1239 \since 6.0
1240*/
1241
1242/*!
1243 \fn int QStringView::toInt(bool *ok, int base) const
1244
1245 Returns the string view converted to an \c int using base \a
1246 base, which is 10 by default and must be between 2 and 36, or 0.
1247 Returns 0 if the conversion fails.
1248
1249 If \a ok is not \nullptr, failure is reported by setting *\a{ok}
1250 to \c false, and success by setting *\a{ok} to \c true.
1251
1252 If \a base is 0, the C language convention is used: if the string view
1253 begins with "0x", base 16 is used; otherwise, if the string view begins with "0",
1254 base 8 is used; otherwise, base 10 is used.
1255
1256 The string conversion will always happen in the 'C' locale. For locale
1257 dependent conversion use QLocale::toInt()
1258
1259 \sa QString::toInt()
1260
1261 \since 6.0
1262*/
1263
1264/*!
1265 \fn uint QStringView::toUInt(bool *ok, int base) const
1266
1267 Returns the string view converted to an \c{unsigned int} using base \a
1268 base, which is 10 by default and must be between 2 and 36, or 0.
1269 Returns 0 if the conversion fails.
1270
1271 If \a ok is not \nullptr, failure is reported by setting *\a{ok}
1272 to \c false, and success by setting *\a{ok} to \c true.
1273
1274 If \a base is 0, the C language convention is used: if the string view
1275 begins with "0x", base 16 is used; otherwise, if the string view begins with "0",
1276 base 8 is used; otherwise, base 10 is used.
1277
1278 The string conversion will always happen in the 'C' locale. For locale
1279 dependent conversion use QLocale::toUInt()
1280
1281 \sa QString::toUInt()
1282
1283 \since 6.0
1284*/
1285
1286/*!
1287 \fn short QStringView::toShort(bool *ok, int base) const
1288
1289 Returns the string view converted to a \c short using base \a
1290 base, which is 10 by default and must be between 2 and 36, or 0.
1291 Returns 0 if the conversion fails.
1292
1293 If \a ok is not \nullptr, failure is reported by setting *\a{ok}
1294 to \c false, and success by setting *\a{ok} to \c true.
1295
1296 If \a base is 0, the C language convention is used: if the string view
1297 begins with "0x", base 16 is used; otherwise, if the string view begins with "0",
1298 base 8 is used; otherwise, base 10 is used.
1299
1300 The string conversion will always happen in the 'C' locale. For locale
1301 dependent conversion use QLocale::toShort()
1302
1303 \sa QString::toShort()
1304
1305 \since 6.0
1306*/
1307
1308/*!
1309 \fn ushort QStringView::toUShort(bool *ok, int base) const
1310
1311 Returns the string view converted to an \c{unsigned short} using base \a
1312 base, which is 10 by default and must be between 2 and 36, or 0.
1313 Returns 0 if the conversion fails.
1314
1315 If \a ok is not \nullptr, failure is reported by setting *\a{ok}
1316 to \c false, and success by setting *\a{ok} to \c true.
1317
1318 If \a base is 0, the C language convention is used: if the string view
1319 begins with "0x", base 16 is used; otherwise, if the string view begins with "0",
1320 base 8 is used; otherwise, base 10 is used.
1321
1322 The string conversion will always happen in the 'C' locale. For locale
1323 dependent conversion use QLocale::toUShort()
1324
1325 \sa QString::toUShort()
1326
1327 \since 6.0
1328*/
1329
1330/*!
1331 \fn double QStringView::toDouble(bool *ok) const
1332
1333 Returns the string view converted to a \c double value.
1334
1335 Returns an infinity if the conversion overflows or 0.0 if the
1336 conversion fails for other reasons (e.g. underflow).
1337
1338 If \a ok is not \nullptr, failure is reported by setting *\a{ok}
1339 to \c false, and success by setting *\a{ok} to \c true.
1340
1341 The string conversion will always happen in the 'C' locale. For locale
1342 dependent conversion use QLocale::toDouble()
1343
1344 For historic reasons, this function does not handle
1345 thousands group separators. If you need to convert such numbers,
1346 use QLocale::toDouble().
1347
1348 \sa QString::toDouble()
1349
1350 \since 6.0
1351*/
1352
1353/*!
1354 \fn float QStringView::toFloat(bool *ok) const
1355
1356 Returns the string view converted to a \c float value.
1357
1358 Returns an infinity if the conversion overflows or 0.0 if the
1359 conversion fails for other reasons (e.g. underflow).
1360
1361 If \a ok is not \nullptr, failure is reported by setting *\a{ok}
1362 to \c false, and success by setting *\a{ok} to \c true.
1363
1364 The string conversion will always happen in the 'C' locale. For locale
1365 dependent conversion use QLocale::toFloat()
1366
1367 \sa QString::toFloat()
1368
1369 \since 6.0
1370*/
1371
1372
1373/*!
1374 \fn template <typename Needle, typename...Flags> auto QStringView::tokenize(Needle &&sep, Flags...flags) const
1375 \fn template <typename Needle, typename...Flags> auto QLatin1StringView::tokenize(Needle &&sep, Flags...flags) const
1376 \fn template <typename Needle, typename...Flags> auto QString::tokenize(Needle &&sep, Flags...flags) const &
1377 \fn template <typename Needle, typename...Flags> auto QString::tokenize(Needle &&sep, Flags...flags) const &&
1378 \fn template <typename Needle, typename...Flags> auto QString::tokenize(Needle &&sep, Flags...flags) &&
1379
1380 Splits the string into substring views wherever \a sep occurs, and
1381 returns a lazy sequence of those strings.
1382
1383 Equivalent to
1384
1385 \code
1386 return QStringTokenizer{std::forward<Needle>(sep), flags...};
1387 \endcode
1388
1389 except it works without C++17 Class Template Argument Deduction (CTAD)
1390 enabled in the compiler.
1391
1392 See QStringTokenizer for how \a sep and \a flags interact to form
1393 the result.
1394
1395 \note While this function returns QStringTokenizer, you should never,
1396 ever, name its template arguments explicitly. If you can use C++17 Class
1397 Template Argument Deduction (CTAD), you may write
1398 \code
1399 QStringTokenizer result = sv.tokenize(sep);
1400 \endcode
1401 (without template arguments). If you can't use C++17 CTAD, you must store
1402 the return value only in \c{auto} variables:
1403 \code
1404 auto result = sv.tokenize(sep);
1405 \endcode
1406 This is because the template arguments of QStringTokenizer have a very
1407 subtle dependency on the specific tokenize() overload from which they are
1408 returned, and they don't usually correspond to the type used for the separator.
1409
1410 \since 6.0
1411 \sa QStringTokenizer, qTokenize()
1412*/
1413
1414QT_END_NAMESPACE
1415

source code of qtbase/src/corelib/text/qstringview.cpp