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

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