ObjFW
OFString.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2008-2025 Jonathan Schleifer <js@nil.im>
3  *
4  * All rights reserved.
5  *
6  * This program is free software: you can redistribute it and/or modify it
7  * under the terms of the GNU Lesser General Public License version 3.0 only,
8  * as published by the Free Software Foundation.
9  *
10  * This program is distributed in the hope that it will be useful, but WITHOUT
11  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12  * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
13  * version 3.0 for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * version 3.0 along with this program. If not, see
17  * <https://www.gnu.org/licenses/>.
18  */
19 
20 #ifndef __STDC_LIMIT_MACROS
21 # define __STDC_LIMIT_MACROS
22 #endif
23 #ifndef __STDC_CONSTANT_MACROS
24 # define __STDC_CONSTANT_MACROS
25 #endif
26 
27 #include "objfw-defs.h"
28 
29 #ifdef OF_HAVE_SYS_TYPES_H
30 # include <sys/types.h>
31 #endif
32 
33 #include <stdarg.h>
34 #include <stdint.h>
35 #ifdef OF_HAVE_INTTYPES_H
36 # include <inttypes.h>
37 #endif
38 
39 #import "OFObject.h"
40 #import "OFJSONRepresentation.h"
41 #import "OFMessagePackRepresentation.h"
42 
43 OF_ASSUME_NONNULL_BEGIN
44 
47 @class OFArray OF_GENERIC(ObjectType);
48 @class OFCharacterSet;
49 @class OFConstantString;
50 @class OFIRI;
51 @class OFString;
52 
53 #if defined(__cplusplus) && __cplusplus >= 201103L
54 typedef char16_t OFChar16;
55 typedef char32_t OFChar32;
56 #else
57 typedef uint_least16_t OFChar16;
58 typedef uint_least32_t OFChar32;
59 #endif
60 typedef OFChar32 OFUnichar;
61 
65 typedef enum {
66  /*
67  * UTF-8 *has* to be 0, so that if the current @ref OFLocale is
68  * `nil`, `[OFLocale encoding]` returns UTF-8.
69  */
105 
111 typedef enum {
115 
121 typedef enum {
125 
126 #ifdef OF_HAVE_BLOCKS
127 
134 typedef void (^OFStringLineEnumerationBlock)(OFString *line, bool *stop);
135 #endif
136 
147 @property (readonly, nonatomic) size_t length;
148 
156 @property (readonly, nonatomic) const char *UTF8String;
157 
161 @property (readonly, nonatomic) size_t UTF8StringLength;
162 
166 @property (readonly, nonatomic) OFString *uppercaseString;
167 
171 @property (readonly, nonatomic) OFString *lowercaseString;
172 
180 @property (readonly, nonatomic) OFString *capitalizedString;
181 
191 @property (readonly, nonatomic) signed char charValue;
192 
202 @property (readonly, nonatomic) short shortValue;
203 
213 @property (readonly, nonatomic) int intValue;
214 
224 @property (readonly, nonatomic) long longValue;
225 
235 @property (readonly, nonatomic) long long longLongValue;
236 
246 @property (readonly, nonatomic) unsigned char unsignedCharValue;
247 
257 @property (readonly, nonatomic) unsigned short unsignedShortValue;
258 
268 @property (readonly, nonatomic) unsigned int unsignedIntValue;
269 
279 @property (readonly, nonatomic) unsigned long unsignedLongValue;
280 
290 @property (readonly, nonatomic) unsigned long long unsignedLongLongValue;
291 
298 @property (readonly, nonatomic) float floatValue;
299 
306 @property (readonly, nonatomic) double doubleValue;
307 
317 @property (readonly, nonatomic) const OFUnichar *characters;
318 
328 @property (readonly, nonatomic) const OFChar16 *UTF16String;
329 
333 @property (readonly, nonatomic) size_t UTF16StringLength;
334 
344 @property (readonly, nonatomic) const OFChar32 *UTF32String;
345 
349 @property (readonly, nonatomic) OFString *stringByDeletingLeadingWhitespaces;
350 
354 @property (readonly, nonatomic) OFString *stringByDeletingTrailingWhitespaces;
355 
359 @property (readonly, nonatomic) OFString *stringByDeletingEnclosingWhitespaces;
360 
361 #if defined(OF_WINDOWS) || defined(DOXYGEN)
362 
365 @property (readonly, nonatomic)
367 #endif
368 
374 + (instancetype)string;
375 
383 + (instancetype)stringWithUTF8String: (const char *)UTF8String;
384 
394 + (instancetype)stringWithUTF8String: (const char *)UTF8String
395  length: (size_t)UTF8StringLength;
396 
412 + (instancetype)stringWithUTF8StringNoCopy: (char *)UTF8String
413  freeWhenDone: (bool)freeWhenDone;
414 
431 + (instancetype)stringWithUTF8StringNoCopy: (char *)UTF8String
432  length: (size_t)UTF8StringLength
433  freeWhenDone: (bool)freeWhenDone;
434 
443 + (instancetype)stringWithCString: (const char *)cString
444  encoding: (OFStringEncoding)encoding;
445 
456 + (instancetype)stringWithCString: (const char *)cString
457  encoding: (OFStringEncoding)encoding
458  length: (size_t)cStringLength;
459 
468 + (instancetype)stringWithData: (OFData *)data
469  encoding: (OFStringEncoding)encoding;
470 
477 + (instancetype)stringWithString: (OFString *)string;
478 
487 + (instancetype)stringWithCharacters: (const OFUnichar *)characters
488  length: (size_t)length;
489 
497 + (instancetype)stringWithUTF16String: (const OFChar16 *)string;
498 
508 + (instancetype)stringWithUTF16String: (const OFChar16 *)string
509  length: (size_t)length;
510 
520 + (instancetype)stringWithUTF16String: (const OFChar16 *)string
521  byteOrder: (OFByteOrder)byteOrder;
522 
534 + (instancetype)stringWithUTF16String: (const OFChar16 *)string
535  length: (size_t)length
536  byteOrder: (OFByteOrder)byteOrder;
537 
544 + (instancetype)stringWithUTF32String: (const OFChar32 *)string;
545 
554 + (instancetype)stringWithUTF32String: (const OFChar32 *)string
555  length: (size_t)length;
556 
565 + (instancetype)stringWithUTF32String: (const OFChar32 *)string
566  byteOrder: (OFByteOrder)byteOrder;
567 
578 + (instancetype)stringWithUTF32String: (const OFChar32 *)string
579  length: (size_t)length
580  byteOrder: (OFByteOrder)byteOrder;
581 
595 + (instancetype)stringWithFormat: (OFConstantString *)format, ...;
596 
597 #ifdef OF_HAVE_FILES
598 
606 + (instancetype)stringWithContentsOfFile: (OFString *)path;
607 
617 + (instancetype)stringWithContentsOfFile: (OFString *)path
618  encoding: (OFStringEncoding)encoding;
619 #endif
620 
634 + (instancetype)stringWithContentsOfIRI: (OFIRI *)IRI;
635 
645 + (instancetype)stringWithContentsOfIRI: (OFIRI *)IRI
646  encoding: (OFStringEncoding)encoding;
647 
653 - (instancetype)init OF_DESIGNATED_INITIALIZER;
654 
663 - (instancetype)initWithUTF8String: (const char *)UTF8String;
664 
674 - (instancetype)initWithUTF8String: (const char *)UTF8String
675  length: (size_t)UTF8StringLength;
676 
692 - (instancetype)initWithUTF8StringNoCopy: (char *)UTF8String
693  freeWhenDone: (bool)freeWhenDone;
694 
712 - (instancetype)initWithUTF8StringNoCopy: (char *)UTF8String
713  length: (size_t)UTF8StringLength
714  freeWhenDone: (bool)freeWhenDone;
715 
725 - (instancetype)initWithCString: (const char *)cString
726  encoding: (OFStringEncoding)encoding;
727 
738 - (instancetype)initWithCString: (const char *)cString
739  encoding: (OFStringEncoding)encoding
740  length: (size_t)cStringLength;
741 
751 - (instancetype)initWithData: (OFData *)data
752  encoding: (OFStringEncoding)encoding;
753 
760 - (instancetype)initWithString: (OFString *)string;
761 
770 - (instancetype)initWithCharacters: (const OFUnichar *)characters
771  length: (size_t)length;
772 
780 - (instancetype)initWithUTF16String: (const OFChar16 *)string;
781 
791 - (instancetype)initWithUTF16String: (const OFChar16 *)string
792  length: (size_t)length;
793 
803 - (instancetype)initWithUTF16String: (const OFChar16 *)string
804  byteOrder: (OFByteOrder)byteOrder;
805 
817 - (instancetype)initWithUTF16String: (const OFChar16 *)string
818  length: (size_t)length
819  byteOrder: (OFByteOrder)byteOrder;
820 
827 - (instancetype)initWithUTF32String: (const OFChar32 *)string;
828 
837 - (instancetype)initWithUTF32String: (const OFChar32 *)string
838  length: (size_t)length;
839 
848 - (instancetype)initWithUTF32String: (const OFChar32 *)string
849  byteOrder: (OFByteOrder)byteOrder;
850 
861 - (instancetype)initWithUTF32String: (const OFChar32 *)string
862  length: (size_t)length
863  byteOrder: (OFByteOrder)byteOrder;
864 
878 - (instancetype)initWithFormat: (OFConstantString *)format, ...;
879 
894 - (instancetype)initWithFormat: (OFConstantString *)format
895  arguments: (va_list)arguments;
896 
897 #ifdef OF_HAVE_FILES
898 
906 - (instancetype)initWithContentsOfFile: (OFString *)path;
907 
917 - (instancetype)initWithContentsOfFile: (OFString *)path
918  encoding: (OFStringEncoding)encoding;
919 #endif
920 
935 - (instancetype)initWithContentsOfIRI: (OFIRI *)IRI;
936 
946 - (instancetype)initWithContentsOfIRI: (OFIRI *)IRI
947  encoding: (OFStringEncoding)encoding;
948 
962 - (size_t)getCString: (char *)cString
963  maxLength: (size_t)maxLength
964  encoding: (OFStringEncoding)encoding;
965 
978 - (size_t)getLossyCString: (char *)cString
979  maxLength: (size_t)maxLength
980  encoding: (OFStringEncoding)encoding;
981 
994 - (const char *)cStringWithEncoding: (OFStringEncoding)encoding;
995 
1008 - (const char *)lossyCStringWithEncoding: (OFStringEncoding)encoding;
1009 
1021 - (const char *)insecureCStringWithEncoding: (OFStringEncoding)encoding;
1022 
1032 - (size_t)cStringLengthWithEncoding: (OFStringEncoding)encoding;
1033 
1040 - (OFComparisonResult)compare: (OFString *)string;
1041 
1048 - (OFComparisonResult)caseInsensitiveCompare: (OFString *)string;
1049 
1056 - (OFUnichar)characterAtIndex: (size_t)index;
1057 
1065 - (void)getCharacters: (OFUnichar *)buffer inRange: (OFRange)range;
1066 
1074 - (OFRange)rangeOfString: (OFString *)string;
1075 
1084 - (OFRange)rangeOfString: (OFString *)string
1085  options: (OFStringSearchOptions)options;
1086 
1096 - (OFRange)rangeOfString: (OFString *)string
1097  options: (OFStringSearchOptions)options
1098  range: (OFRange)range;
1099 
1107 - (OFRange)rangeOfCharacterFromSet: (OFCharacterSet *)characterSet;
1108 
1117 - (OFRange)rangeOfCharacterFromSet: (OFCharacterSet *)characterSet
1118  options: (OFStringSearchOptions)options;
1119 
1129 - (OFRange)rangeOfCharacterFromSet: (OFCharacterSet *)characterSet
1130  options: (OFStringSearchOptions)options
1131  range: (OFRange)range;
1132 
1140 - (size_t)indexOfCharacterFromSet: (OFCharacterSet *)characterSet
1141  OF_DEPRECATED(ObjFW, 1, 3, "Use -[rangeOfCharacterFromSet:] instead");
1142 
1151 - (size_t)indexOfCharacterFromSet: (OFCharacterSet *)characterSet
1152  options: (OFStringSearchOptions)options
1153  OF_DEPRECATED(ObjFW, 1, 3,
1154  "Use -[rangeOfCharacterFromSet:options:] instead");
1155 
1165 - (size_t)indexOfCharacterFromSet: (OFCharacterSet *)characterSet
1166  options: (OFStringSearchOptions)options
1167  range: (OFRange)range
1168  OF_DEPRECATED(ObjFW, 1, 3,
1169  "Use -[rangeOfCharacterFromSet:options:range:] instead");
1170 
1177 - (bool)containsString: (OFString *)string;
1178 
1185 - (OFString *)substringFromIndex: (size_t)idx;
1186 
1193 - (OFString *)substringToIndex: (size_t)idx;
1194 
1201 - (OFString *)substringWithRange: (OFRange)range;
1202 
1217 - (signed char)charValueWithBase: (unsigned char)base;
1218 
1233 - (short)shortValueWithBase: (unsigned char)base;
1234 
1249 - (int)intValueWithBase: (unsigned char)base;
1250 
1265 - (long)longValueWithBase: (unsigned char)base;
1266 
1281 - (long long)longLongValueWithBase: (unsigned char)base;
1282 
1297 - (unsigned char)unsignedCharValueWithBase: (unsigned char)base;
1298 
1313 - (unsigned short)unsignedShortValueWithBase: (unsigned char)base;
1314 
1329 - (unsigned int)unsignedIntValueWithBase: (unsigned char)base;
1330 
1345 - (unsigned long)unsignedLongValueWithBase: (unsigned char)base;
1346 
1362 - (unsigned long long)unsignedLongLongValueWithBase: (unsigned char)base;
1363 
1370 - (OFString *)stringByAppendingString: (OFString *)string;
1371 
1381 - (OFString *)stringByAppendingFormat: (OFConstantString *)format, ...;
1382 
1393 - (OFString *)stringByAppendingFormat: (OFConstantString *)format
1394  arguments: (va_list)arguments;
1395 
1404 - (OFString *)stringByReplacingOccurrencesOfString: (OFString *)string
1405  withString: (OFString *)replacement;
1406 
1419 - (OFString *)stringByReplacingOccurrencesOfString: (OFString *)string
1420  withString: (OFString *)replacement
1421  options: (int)options
1422  range: (OFRange)range;
1423 
1430 - (bool)hasPrefix: (OFString *)prefix;
1431 
1438 - (bool)hasSuffix: (OFString *)suffix;
1439 
1447 - (OFArray OF_GENERIC(OFString *) *)
1448  componentsSeparatedByString: (OFString *)delimiter;
1449 
1458 - (OFArray OF_GENERIC(OFString *) *)
1459  componentsSeparatedByString: (OFString *)delimiter
1460  options: (OFStringSeparationOptions)options;
1461 
1469 - (OFArray OF_GENERIC(OFString *) *)
1470  componentsSeparatedByCharactersInSet: (OFCharacterSet *)characterSet;
1471 
1480 - (OFArray OF_GENERIC(OFString *) *)
1481  componentsSeparatedByCharactersInSet: (OFCharacterSet *)characterSet
1482  options: (OFStringSeparationOptions)options;
1483 
1497 - (const OFChar16 *)UTF16StringWithByteOrder: (OFByteOrder)byteOrder;
1498 
1511 - (const OFChar32 *)UTF32StringWithByteOrder: (OFByteOrder)byteOrder;
1512 
1521 - (OFData *)dataWithEncoding: (OFStringEncoding)encoding;
1522 
1523 #ifdef OF_HAVE_FILES
1524 
1529 - (void)writeToFile: (OFString *)path;
1530 
1540 - (void)writeToFile: (OFString *)path encoding: (OFStringEncoding)encoding;
1541 #endif
1542 
1548 - (void)writeToIRI: (OFIRI *)IRI;
1549 
1558 - (void)writeToIRI: (OFIRI *)IRI encoding: (OFStringEncoding)encoding;
1559 
1560 #ifdef OF_HAVE_BLOCKS
1561 
1566 - (void)enumerateLinesUsingBlock: (OFStringLineEnumerationBlock)block;
1567 #endif
1568 @end
1569 
1570 #ifdef __cplusplus
1571 extern "C" {
1572 #endif
1573 
1584 
1591 extern OFString *_Nullable OFStringEncodingName(OFStringEncoding encoding);
1592 
1599 extern size_t OFUTF16StringLength(const OFChar16 *string);
1600 
1607 extern size_t OFUTF32StringLength(const OFChar32 *string);
1608 #ifdef __cplusplus
1609 }
1610 #endif
1611 
1612 OF_ASSUME_NONNULL_END
1613 
1614 #import "OFConstantString.h"
1615 #import "OFMutableString.h"
1616 #import "OFString+CryptographicHashing.h"
1617 #import "OFString+JSONParsing.h"
1618 #ifdef OF_HAVE_FILES
1619 # import "OFString+PathAdditions.h"
1620 #endif
1621 #import "OFString+PercentEncoding.h"
1622 #import "OFString+PropertyListParsing.h"
1623 #import "OFString+XMLEscaping.h"
1624 #import "OFString+XMLUnescaping.h"
1625 
1626 #if !defined(NSINTEGER_DEFINED) && !__has_feature(modules)
1627 /*
1628  * Very *ugly* hack required for string boxing literals to work.
1629  *
1630  * This hack is needed in order to work with `@class NSString` from Apple's
1631  * objc/NSString.h - which is included when using modules - as
1632  * @compatibility_alias does not work if @class has been used before.
1633  * For some reason, this makes Clang refer to OFString for string box literals
1634  * and not to NSString (which would result in a linker error, but would be the
1635  * correct behavior).
1636  *
1637  * TODO: Submit a patch for Clang that makes the boxing classes configurable!
1638  */
1639 @interface NSString: OFString
1640 @end
1641 #endif
OFStringSeparationOptions
Options for separating strings.
Definition: OFString.h:121
Definition: OFString.h:103
An abstract class for storing objects in an array.
Definition: OFArray.h:107
signed char charValue
The decimal value of the string as a char.
Definition: OFString.h:191
instancetype init()
Initializes an already allocated OFString to be empty.
Definition: OFString.m:901
A protocol for comparing objects.
Definition: OFObject.h:1392
OFStringEncoding
The encoding of a string.
Definition: OFString.h:65
Definition: OFString.h:81
OFString * stringByExpandingWindowsEnvironmentStrings
The string with the Windows Environment Strings expanded.
Definition: OFString.h:366
OFString * capitalizedString
The string in capitalized form.
Definition: OFString.h:180
OFString * stringByDeletingEnclosingWhitespaces
The string with leading and trailing whitespaces deleted.
Definition: OFString.h:359
unsigned int unsignedIntValue
The decimal value of the string as an unsigned int.
Definition: OFString.h:268
size_t OFUTF32StringLength(const OFChar32 *string)
Returns the length of the specified UTF-32 string.
Definition: OFString.m:359
int intValue
The decimal value of the string as an int.
Definition: OFString.h:213
Definition: OFString.h:89
A class for storing constant strings using the @"" literal.
Definition: OFConstantString.h:41
The root class for all other classes inside ObjFW.
Definition: OFObject.h:690
OFString * uppercaseString
The string in uppercase.
Definition: OFString.h:166
Definition: OFString.h:93
A class cluster representing a character set.
Definition: OFCharacterSet.h:32
unsigned char unsignedCharValue
The decimal value of the string as an unsigned char.
Definition: OFString.h:246
OFStringEncoding OFStringEncodingParseName(OFString *name)
Parses the specified string encoding name and returns the OFStringEncoding for it.
Definition: OFString.m:167
OFString * stringByDeletingTrailingWhitespaces
The string with trailing whitespaces deleted.
Definition: OFString.h:354
unsigned long unsignedLongValue
The decimal value of the string as an unsigned long.
Definition: OFString.h:279
Definition: OFString.h:123
Definition: OFString.h:113
const OFUnichar * characters
The string as an array of Unicode characters.
Definition: OFString.h:317
A protocol implemented by classes that support encoding to a JSON representation. ...
Definition: OFJSONRepresentation.h:49
A class for handling strings.
Definition: OFString.h:142
Definition: OFString.h:87
const OFChar32 * UTF32String
The string in UTF-32 encoding with native byte order.
Definition: OFString.h:344
OFString * lowercaseString
The string in lowercase.
Definition: OFString.h:171
size_t OFUTF16StringLength(const OFChar16 *string)
Returns the length of the specified UTF-16 string.
Definition: OFString.m:348
OFComparisonResult
A result of a comparison.
Definition: OFObject.h:58
Definition: OFString.h:79
const OFChar16 * UTF16String
The string in UTF-16 encoding with native byte order.
Definition: OFString.h:328
Definition: OFString.h:71
Definition: OFString.h:101
OFByteOrder
An enum for representing endianness.
Definition: OFObject.h:92
Definition: OFString.h:77
Definition: OFString.h:99
size_t UTF16StringLength
The length of the string in UTF-16 characters.
Definition: OFString.h:333
A protocol implemented by classes that support encoding to a MessagePack representation.
Definition: OFMessagePackRepresentation.h:33
OFString * stringByDeletingLeadingWhitespaces
The string with leading whitespaces deleted.
Definition: OFString.h:349
size_t UTF8StringLength
The number of bytes the string needs in UTF-8 encoding.
Definition: OFString.h:161
Definition: OFString.h:91
A class for representing IRIs, URIs, URLs and URNs, for parsing them as well as accessing parts of th...
Definition: OFIRI.h:39
long long longLongValue
The decimal value of the string as a long long.
Definition: OFString.h:235
Definition: OFString.h:97
A protocol for the creation of mutable copies.
Definition: OFObject.h:1375
A protocol for the creation of copies.
Definition: OFObject.h:1354
A class for storing arbitrary data in an array.
Definition: OFData.h:45
unsigned short unsignedShortValue
The decimal value of the string as an unsigned short.
Definition: OFString.h:257
size_t length
The length of the string in Unicode code points.
Definition: OFString.h:147
Definition: OFString.h:75
Definition: OFString.h:83
void(^ OFStringLineEnumerationBlock)(OFString *line, bool *stop)
A block for enumerating the lines of a string.
Definition: OFString.h:134
const char * UTF8String
The OFString as a UTF-8 encoded C string.
Definition: OFString.h:156
double doubleValue
The double value of the string as a double.
Definition: OFString.h:306
long longValue
The decimal value of the string as a long.
Definition: OFString.h:224
short shortValue
The decimal value of the string as a short.
Definition: OFString.h:202
float floatValue
The float value of the string as a float.
Definition: OFString.h:298
instancetype string()
Creates a new OFString.
Definition: OFString.m:735
unsigned long long unsignedLongLongValue
The decimal value of the string as an unsigned long long.
Definition: OFString.h:290
Definition: OFString.h:95
A range.
Definition: OFObject.h:110
Definition: OFString.h:85
Definition: OFString.h:73
OFStringSearchOptions
Options for searching in strings.
Definition: OFString.h:111
OFString * OFStringEncodingName(OFStringEncoding encoding)
Returns the name of the specified OFStringEncoding.
Definition: OFString.m:229