1
#ifndef _KVI_QSTRING_H_
2
#define _KVI_QSTRING_H_
3
//=============================================================================
5
// File : kvi_qstring.h
6
// Creation date : Mon Aug 04 2003 13:36:33 CEST by Szymon Stefanek
8
// This file is part of the KVirc irc client distribution
9
// Copyright (C) 2003-2008 Szymon Stefanek (pragma at kvirc dot net)
11
// This program is FREE software. You can redistribute it and/or
12
// modify it under the terms of the GNU General Public License
13
// as published by the Free Software Foundation; either version 2
14
// of the License, or (at your opinion) any later version.
16
// This program is distributed in the HOPE that it will be USEFUL,
17
// but WITHOUT ANY WARRANTY; without even the implied warranty of
18
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
19
// See the GNU General Public License for more details.
21
// You should have received a copy of the GNU General Public License
22
// along with this program. If not, write to the Free Software Foundation,
23
// Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
25
//=============================================================================
29
* \author Szymon Stefanek
30
* \brief Helper functions for the QString class
33
#include "kvi_settings.h"
34
#include "kvi_inttypes.h"
35
#include "kvi_stdarg.h"
41
* \namespace KviQString
42
* \brief A namespace for QString helper functions
44
* This namespace contains several helper functions that are used when dealing
50
* \brief A global empty string (note that this is ALSO NULL under Qt 3.x)
52
extern KVILIB_API const QString Empty;
55
* \brief Returns a readable size in byte's multiples
57
* This will return strings like KiB, MiB, GiB, TiB and so on
58
* \param size The size of the file
61
extern KVILIB_API QString makeSizeReadable(quint64 size);
64
* \brief Compares two strings with case sensitive
66
* It returns true if the strings are equal, false otherwise
67
* \param sz1 First string
68
* \param sz2 Second string
71
extern KVILIB_API bool equalCS(const QString & sz1, const QString & sz2);
74
* \brief Compares two strings with case sensitive
76
* It returns true if the strings are equal, false otherwise
77
* \param sz1 First string
78
* \param pc2 Second string
81
extern KVILIB_API bool equalCS(const QString & sz1, const char * pc2);
84
* \brief Compares two strings with case sensitive
86
* It returns true if the strings are equal, false otherwise
87
* \param pc1 First string
88
* \param sz2 Second string
91
inline bool equalCS(const char * pc1, const QString & sz2)
92
{ return equalCS(sz2,pc1); }
95
* \brief Compares two strings with case insensitive
97
* It returns true if the strings are equal, false otherwise
98
* \param sz1 First string
99
* \param sz2 Second string
102
extern KVILIB_API bool equalCI(const QString & sz1, const QString & sz2);
105
* \brief Compares two strings with case insensitive
107
* It returns true if the strings are equal, false otherwise
108
* \param sz1 First string
109
* \param pc2 Second string
112
extern KVILIB_API bool equalCI(const QString & sz1, const char * pc2);
115
* \brief Compares two strings with case insensitive
117
* It returns true if the strings are equal, false otherwise.
118
* The parameter pC2 is assumed to be null terminated here!
119
* \param sz1 First string
120
* \param pC2 Second string
123
extern KVILIB_API bool equalCI(const QString & sz1, const QChar * pC2);
126
* \brief Compares two strings with case insensitive
128
* It returns true if the strings are equal, false otherwise.
129
* \param pc1 First string
130
* \param sz2 Second string
133
inline bool equalCI(const char * pc1, const QString & sz2)
134
{ return equalCI(sz2,pc1); }
137
* \brief Compares two strings with case insensitive
139
* It returns true if the strings are equal, false otherwise.
140
* The parameter pC1 is assumed to be null terminated here!
141
* \param pC1 First string
142
* \param sz2 Second string
145
inline bool equalCI(const QChar * pC1, const QString & sz2)
146
{ return equalCI(sz2,pC1); }
149
* \brief Compares two strings with case sensitive up to N chars
151
* It returns true if the strings are equal, false otherwise
152
* \param sz1 First string
153
* \param sz2 Second string
154
* \param uLen The length of the string to check
157
extern KVILIB_API bool equalCSN(const QString & sz1, const QString & sz2, unsigned int uLen);
160
* \brief Compares two strings with case sensitive up to N chars
162
* It returns true if the strings are equal, false otherwise
163
* \param sz1 First string
164
* \param pc2 Second string
165
* \param uLen The length of the string to check
168
extern KVILIB_API bool equalCSN(const QString & sz1, const char * pc2, unsigned int uLen);
171
* \brief Compares two strings with case sensitive up to N chars
173
* It returns true if the strings are equal, false otherwise
174
* \param pc1 First string
175
* \param sz2 Second string
176
* \param uLen The length of the string to check
179
inline bool equalCSN(const char * pc1, const QString & sz2, unsigned int uLen)
180
{ return equalCSN(sz2,pc1,uLen); }
183
* \brief Compares two strings with case insensitive up to N chars
185
* It returns true if the strings are equal, false otherwise
186
* \param sz1 First string
187
* \param sz2 Second string
188
* \param uLen The length of the string to check
191
extern KVILIB_API bool equalCIN(const QString & sz1, const QString & sz2, unsigned int uLen);
194
* \brief Compares two strings with case insensitive up to N chars
196
* It returns true if the strings are equal, false otherwise
197
* \param sz1 First string
198
* \param pc2 Second string
199
* \param uLen The length of the string to check
202
extern KVILIB_API bool equalCIN(const QString & sz1, const char * pc2, unsigned int uLen);
205
* \brief Compares two strings with case insensitive up to N chars
207
* It returns true if the strings are equal, false otherwise
208
* pC2 is assumed to be null terminated here!
209
* \param sz1 First string
210
* \param pC2 Second string
211
* \param uLen The length of the string to check
214
extern KVILIB_API bool equalCIN(const QString & sz1, const QChar * pC2, unsigned int uLen);
217
* \brief Compares two strings with case insensitive up to N chars
219
* It returns true if the strings are equal, false otherwise
220
* \param pc1 First string
221
* \param sz2 Second string
222
* \param uLen The length of the string to check
225
inline bool equalCIN(const char * pc1, const QString & sz2, unsigned int uLen)
226
{ return equalCIN(sz2,pc1,uLen); }
229
* \brief Compares two strings with case insensitive up to N chars
231
* It returns true if the strings are equal, false otherwise
232
* pC1 is assumed to be null terminated here!
233
* \param pC1 First string
234
* \param sz2 Second string
235
* \param uLen The length of the string to check
238
inline bool equalCIN(const QChar * pC1, const QString & sz2, unsigned int uLen)
239
{ return equalCIN(sz2,pC1,uLen); }
242
* \brief Compares two strings with case insensitive
244
* Note that greater here means that come AFTER in the alphabetic order
245
* return < 0 ---> str1 < str2
246
* return = 0 ---> str1 = str2
247
* return > 0 ---> str1 > str2
248
* \param sz1 The first string
249
* \param sz2 The second string
250
* \param bNonAlphaGreater Wheter to check if strings are not alphabetics
253
extern KVILIB_API int cmpCI(const QString & sz1, const QString & sz2, bool bNonAlphaGreater = false);
256
* \brief Compares two strings with case insensitive up to N chars
258
* Note that greater here means that come AFTER in the alphabetic order
259
* return < 0 ---> str1 < str2
260
* return = 0 ---> str1 = str2
261
* return > 0 ---> str1 > str2
262
* \param sz1 The first string
263
* \param sz2 The second string
264
* \param uLen The number of chars to check
267
extern KVILIB_API int cmpCIN(const QString & sz1, const QString & sz2, unsigned int uLen);
270
* \brief Compares two strings with case sensitive
272
* Note that greater here means that come AFTER in the alphabetic order
273
* return < 0 ---> str1 < str2
274
* return = 0 ---> str1 = str2
275
* return > 0 ---> str1 > str2
276
* \param sz1 The first string
277
* \param sz2 The second string
280
extern KVILIB_API int cmpCS(const QString & sz1, const QString & sz2);
283
* \brief Resets the size of the string
284
* \param szSrc The source string
287
extern KVILIB_API void detach(QString & szSrc);
290
* \brief Returns a pointer to the data stored in the string.
292
* This makes the string szSrc appear as a null terminated array.
293
* It MAY RETURN 0 when the string is null!
294
* \param szSrc The source string
297
extern KVILIB_API const QChar * nullTerminatedArray(const QString & szSrc);
300
* \brief Returns true if the string ends with the given character
301
* \param szSrc The source string
302
* \param c The char to check
305
inline bool lastCharIs(QString & szSrc, const QChar & c)
306
{ return szSrc.endsWith(c); }
309
* \brief Ensures the last char of a string is the given char
311
* If the string does not end with the given char, it appends it
312
* \param szSrc The source string
313
* \param c The char to check
316
extern KVILIB_API void ensureLastCharIs(QString & szSrc, const QChar & c);
319
* \brief Matches two strings containging wildcards (* and ?)
320
* \param szM1 The first string to match
321
* \param szM2 The second string to match
324
extern KVILIB_API bool matchWildExpressions(const QString & szM1, const QString & szM2);
327
* \brief Matches two string containging wildcards (* and ?) or regular expressions
328
* \param szExp The regular expression to match
329
* \param szStr The source string
330
* \param bIsRegExp Wheter to use a wildcard or regexp matching
331
* \param bExact Wheter to match the whole string
332
* \param bCs Wheter to match with case sensitive
335
extern KVILIB_API bool matchString(const QString & szExp, const QString & szStr, bool bIsRegExp = false, bool bExact = false, bool bCs = false);
338
* \brief Writes to the character string
339
* \param szSrc The source string
340
* \param szFmt The format string
341
* \param list The list of format parameters
344
extern KVILIB_API void vsprintf(QString & szSrc, const QString & szFmt, kvi_va_list list);
347
* \brief Writes to the character string
348
* \param szSrc The source string
349
* \param szFmt The format string
350
* \param ... The list of format parameters
353
extern KVILIB_API QString & sprintf(QString & szSrc, const QString & szFmt, ...);
356
* \brief Trims all the whitespaces at the end of the given string
357
* \param szSrc The source string
360
extern KVILIB_API void stripRightWhiteSpace(QString & szSrc);
363
* \brief Trims all c chars at the start of the given string
364
* \param szSrc The source string
365
* \param c The char to trim
368
extern KVILIB_API void stripLeft(QString & szSrc, const QChar & c);
371
* \brief Trims all c chars at the end of the given string
372
* \param szSrc The source string
373
* \param c The char to trim
376
extern KVILIB_API void stripRight(QString & szSrc, const QChar & c);
379
* \brief Appends a formatted string
380
* \param szSrc The source string
381
* \param szFmt The format string
382
* \param ... Format string parameters
385
extern KVILIB_API void appendFormatted(QString & szSrc, const QString & szFmt, ...);
388
* \brief Appends the given number to the source string
389
* \param szSrc The source string
390
* \param dReal Number in double format
393
extern KVILIB_API void appendNumber(QString & szSrc, double dReal);
396
* \brief Appends the given number to the source string
397
* \param szSrc The source string
398
* \param iInteger Number in kvi_i64_t format
401
extern KVILIB_API void appendNumber(QString & szSrc, kvi_i64_t iInteger);
404
* \brief Appends the given number to the source string
405
* \param szSrc The source string
406
* \param iInteger Number in int format
409
extern KVILIB_API void appendNumber(QString & szSrc, int iInteger);
412
* \brief Appends the given number to the source string
413
* \param szSrc The source string
414
* \param uInteger Number in unsigned int format
417
extern KVILIB_API void appendNumber(QString & szSrc, unsigned int uInteger);
420
* \brief Appends the given number to the source string
421
* \param szSrc The source string
422
* \param uInteger Number in kvi_i64_t format
425
extern KVILIB_API void appendNumber(QString & szSrc, kvi_u64_t uInteger);
428
* \brief Cuts the string after the first occurrence of the given char
430
* If the char is not found, the string is returned as it is.
431
* \param szSrc The source string
432
* \param c The char to search for
433
* \param bIncluded Wheter to include the given char
436
extern KVILIB_API void cutFromFirst(QString & szSrc, const QChar & c, bool bIncluded = true);
439
* \brief Cuts the string after the first occurrence of the given char
441
* If the char is not found, the string is returned as it is.
442
* \param szSrc The source string
443
* \param szFind The string to search for
444
* \param bIncluded Wheter to include the given string
447
extern KVILIB_API void cutFromFirst(QString & szSrc, const QString & szFind, bool bIncluded = true);
450
* \brief Cuts the string after the last occurrence of the given char
452
* If the char is not found, the string is returned as it is.
453
* \param szSrc The source string
454
* \param c The char to search for
455
* \param bIncluded Wheter to include the given char
458
extern KVILIB_API void cutFromLast(QString & szSrc, const QChar & c, bool bIncluded = true);
461
* \brief Cuts the string after the last occurrence of the given char
463
* If the char is not found, the string is returned as it is.
464
* \param szSrc The source string
465
* \param szFind The string to search for
466
* \param bIncluded Wheter to include the given string
469
extern KVILIB_API void cutFromLast(QString & szSrc, const QString & szFind, bool bIncluded = true);
472
* \brief Cuts the string until the first occurrence of the given char is found
474
* If the char is not found, the string is returned as it is.
475
* \param szSrc The source string
476
* \param c The char to search for
477
* \param bIncluded Wheter to include the given char in the cut
478
* \param bClearIfNotFound Wheter to cut the whole string if the char is not found
481
extern KVILIB_API void cutToFirst(QString & szSrc, const QChar & c, bool bIncluded = true, bool bClearIfNotFound = false);
484
* \brief Cuts the string until the first occurrence of the given char is found
486
* If the char is not found, the string is returned as it is.
487
* \param szSrc The source string
488
* \param szFind The string to search for
489
* \param bIncluded Wheter to include the given string in the cut
490
* \param bClearIfNotFound Wheter to cut the whole string if the string is not found
493
extern KVILIB_API void cutToFirst(QString & szSrc, const QString & szFind, bool bIncluded = true, bool bClearIfNotFound = false);
496
* \brief Cuts the string until the last occurrence of the given char is found
498
* If the char is not found, the string is returned as it is.
499
* \param szSrc The source string
500
* \param c The char to search for
501
* \param bIncluded Wheter to include the given char in the cut
502
* \param bClearIfNotFound Wheter to cut the whole string if the char is not found
505
extern KVILIB_API void cutToLast(QString & szSrc, const QChar & c, bool bIncluded = true, bool bClearIfNotFound = false);
508
* \brief Cuts the string until the last occurrence of the given char is found
510
* If the char is not found, the string is returned as it is.
511
* \param szSrc The source string
512
* \param szFind The string to search for
513
* \param bIncluded Wheter to include the given string in the cut
514
* \param bClearIfNotFound Wheter to cut the whole string if the string is not found
517
extern KVILIB_API void cutToLast(QString & szSrc, const QString & szFind, bool bIncluded = true, bool bClearIfNotFound = false);
520
* \brief Returns the string up to the the first occurrence of the given char
522
* If the char is not found, the string is returned as it is.
523
* \param szSrc The source string
524
* \param c The char to search for
525
* \param bIncluded Wheter to include the given char in the returned string
526
* \param bReturnFullStringIfNotFound True if we want the function to return the whole string if the char isn't found and
527
* false if we want the function to return an empty string in this case.
530
extern KVILIB_API QString leftToFirst(QString & szSrc, const QChar & c, bool bIncluded = true, bool bReturnFullStringIfNotFound = true);
533
* \brief Returns the string up to the first occurrence of the given string
535
* If the char is not found, the string is returned as it is.
536
* \param szSrc The source string
537
* \param szFind The string to search for
538
* \param bIncluded Wheter to include the given string in the returned string
539
* \param bReturnFullStringIfNotFound True if we want the function to return the whole string if the string isn't found and
540
* false if we want the function to return an empty string in this case.
543
extern KVILIB_API QString leftToFirst(QString & szSrc, const QString & szFind, bool bIncluded = true, bool bReturnFullStringIfNotFound = true);
546
* \brief Returns the string up to the last occurrence of the given char
548
* If the char is not found, the string is returned as it is.
549
* \param szSrc The source string
550
* \param c The char to search for
551
* \param bIncluded Wheter to include the given char in the returned string
552
* \param bReturnFullStringIfNotFound True if we want the function to return the whole string if the char isn't found and
553
* false if we want the function to return an empty string in this case.
556
extern KVILIB_API QString leftToLast(QString & szSrc, const QChar & c, bool bIncluded = true, bool bReturnFullStringIfNotFound = true);
559
* \brief Returns the string up to the last occurrence of the given string
561
* If the char is not found, the string is returned as it is.
562
* \param szSrc The source string
563
* \param szFind The string to search for
564
* \param bIncluded Wheter to include the given string in the returned string
565
* \param bReturnFullStringIfNotFound True if we want the function to return the whole string if the string isn't found and
566
* false if we want the function to return an empty string in this case.
569
extern KVILIB_API QString leftToLast(QString & szSrc, const QString & szFind, bool bIncluded = true, bool bReturnFullStringIfNotFound = true);
572
* \brief Returns an ISO-8859-1 upper case string
573
* \param szSrc The source string
576
extern KVILIB_API QString upperISO88591(const QString & szSrc);
579
* \brief Returns an ISO-8859-1 lower case string
580
* \param szSrc The source string
583
extern KVILIB_API QString lowerISO88591(const QString & szSrc);
586
* \brief Returns a token from a string
587
* \param szSrc The source string
588
* \param sep The token to find
591
extern KVILIB_API QString getToken(QString & szSrc, const QChar & sep);
594
* \brief Replaces a string with another
595
* \param szSrc The source string
596
* \param szToFind The string to replace
597
* \param szReplacement The string to replace with
600
extern KVILIB_API void transliterate(QString & szSrc, const QString & szToFind, const QString & szReplacement);
603
* \brief Returns an hexadecimal converted string starting from a buffer
604
* \param szRetBuffer The buffer to hold the hexadecimal string
605
* \param pcBuffer The buffer containing the string to convert
606
* \param uLen The max length of the original string
608
extern KVILIB_API void bufferToHex(QString & szRetBuffer, const unsigned char * pcBuffer, unsigned int uLen);
611
* \brief Returns the index position of the last occurrence of the character
613
* The search is made forward starting from index.
614
* \param szSrc The source string
615
* \param c The character to find
616
* \param iIndex The index to start from
617
* \param bCs Case sensitive search
620
inline int find(const QString & szSrc, QChar c, int iIndex = 0, bool bCs = true)
622
return szSrc.indexOf(c,iIndex,bCs ? Qt::CaseSensitive : Qt::CaseInsensitive);
626
* \brief Returns the index position of the last occurrence of the character
628
* The search is made forward starting from index.
629
* \param szSrc The source string
630
* \param c The character to find
631
* \param iIndex The index to start from
632
* \param bCs Case sensitive search
635
inline int find(const QString & szSrc, char c, int iIndex = 0, bool bCs = true)
637
return szSrc.indexOf(c,iIndex,bCs ? Qt::CaseSensitive : Qt::CaseInsensitive);
641
* \brief Returns the index position of the last occurrence of the string
643
* The search is made forward starting from index.
644
* \param szSrc The source string
645
* \param szStr The string to find
646
* \param iIndex The index to start from
647
* \param bCs Case sensitive search
650
inline int find(const QString & szSrc, const QString & szStr, int iIndex = 0, bool bCs = true)
652
return szSrc.indexOf(szStr,iIndex,bCs ? Qt::CaseSensitive : Qt::CaseInsensitive);
656
* \brief Returns the index position of the last occurrence of the string
658
* The search is made forward starting from index.
659
* \param szSrc The source string
660
* \param pcStr The string to find
661
* \param iIndex The index to start from
662
* \param bCs Case sensitive search
665
inline int find(const QString & szSrc, const char * pcStr, int iIndex = 0, bool bCs = true)
667
return szSrc.indexOf(QString(pcStr),iIndex,bCs ? Qt::CaseSensitive : Qt::CaseInsensitive);
671
* \brief Returns the index position of the last occurrence of the string
673
* The search is made forward starting from index.
674
* \param szSrc The source string
675
* \param rx The regexp to match
676
* \param iIndex The index to start from
679
inline int find(const QString & szSrc, const QRegExp & rx, int iIndex = 0)
681
return szSrc.indexOf(rx,iIndex);
685
* \brief Returns the index position of the last occurrence of the character
687
* The search is made backward.
688
* If index is -1 the search starts at the last character.
689
* \param szSrc The source string
690
* \param c The character to find
691
* \param iIndex The index to start from
692
* \param bCs Case sensitive search
695
inline int findRev(const QString & szSrc, QChar c, int iIndex = -1, bool bCs = true)
697
return szSrc.lastIndexOf(c,iIndex,bCs ? Qt::CaseSensitive : Qt::CaseInsensitive);
701
* \brief Returns the index position of the last occurrence of the character
703
* The search is made backward.
704
* If index is -1 the search starts at the last character.
705
* \param szSrc The source string
706
* \param c The character to find
707
* \param iIndex The index to start from
708
* \param bCs Case sensitive search
711
inline int findRev(const QString & szSrc, char c, int iIndex = -1, bool bCs = true)
713
return szSrc.lastIndexOf(c,iIndex,bCs ? Qt::CaseSensitive : Qt::CaseInsensitive);
717
* \brief Returns the index position of the last occurrence of the given string
719
* The search is made backward.
720
* If index is -1 the search starts at the last character.
721
* \param szSrc The source string
722
* \param szStr The string to find
723
* \param iIndex The index to start from
724
* \param bCs Case sensitive search
727
inline int findRev(const QString & szSrc, const QString & szStr, int iIndex = -1, bool bCs = true)
729
return szSrc.lastIndexOf(szStr,iIndex,bCs ? Qt::CaseSensitive : Qt::CaseInsensitive);
733
* \brief Returns the index position of the last occurrence of the given string
735
* The search is made backward.
736
* If index is -1 the search starts at the last character.
737
* \param szSrc The source string
738
* \param pcStr The string to find
739
* \param iIndex The index to start from
740
* \param bCs Case sensitive search
743
inline int findRev(const QString & szSrc, const char * pcStr, int iIndex = -1, bool bCs = true)
745
return szSrc.lastIndexOf(QString(pcStr),iIndex,bCs ? Qt::CaseSensitive : Qt::CaseInsensitive);
749
* \brief Returns the index position of the last match of the regexp
751
* The search is made backward.
752
* If index is -1 the search starts at the last character.
753
* \param szSrc The source string
754
* \param rx The regexp to match
755
* \param iIndex The index to start from
758
inline int findRev(const QString & szSrc, const QRegExp & rx, int iIndex = -1)
760
return szSrc.lastIndexOf(rx,iIndex);
764
* \brief Return a whitespace-trimmed string
766
* Spaces are trimmed at start and end of the string
767
* \param szSrc The source string
770
inline QString trimmed(const QString & szSrc)
772
return szSrc.trimmed();
776
* \brief Return a UTF-8 formatted string
777
* \param szSrc The source string
779
* \warning: DO NOT USE CONSTRUCTS LIKE char * c = KviQString::toUtf8(something).data();
780
* They are dangerous since with many compilers the returned string
781
* gets destroyed at the end of the instruction and the c pointer gets
784
* QByteArray tmp = KviQString::toUtf8(something);
785
* char * c = tmp.data();
786
* instead. Yes, I know that it sucks, but it's the only way to
787
* transit to Qt 4.x more or less cleanly...
789
inline QByteArray toUtf8(const QString & szSrc)
791
return szSrc.toUtf8();
795
* \brief Return the local 8-bit representation of the string
796
* \param szSrc The source string
799
inline QByteArray toLocal8Bit(const QString & szSrc)
801
return szSrc.toLocal8Bit();
805
* \brief Return the string converted to a long
806
* \param szNumber The source number
807
* \param bOk The conversion error handling
810
inline kvi_i64_t toI64(QString & szNumber, bool * bOk)
812
#if SYSTEM_SIZE_OF_LONG_INT == 8
813
return szNumber.toLong(bOk);
815
return szNumber.toLongLong(bOk);
820
* \brief Return the string converted to an unsigned long
821
* \param szNumber The source number
822
* \param bOk The conversion error handling
825
inline kvi_u64_t toU64(QString & szNumber, bool * bOk)
827
#if SYSTEM_SIZE_OF_LONG_INT == 8
828
return szNumber.toULong(bOk);
830
return szNumber.toULongLong(bOk);
835
#endif //_KVI_QSTRING_H_