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