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