ObjFW
OFString.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015
3  * Jonathan Schleifer <js@webkeks.org>
4  *
5  * All rights reserved.
6  *
7  * This file is part of ObjFW. It may be distributed under the terms of the
8  * Q Public License 1.0, which can be found in the file LICENSE.QPL included in
9  * the packaging of this file.
10  *
11  * Alternatively, it may be distributed under the terms of the GNU General
12  * Public License, either version 2 or 3, which can be found in the file
13  * LICENSE.GPLv2 or LICENSE.GPLv3 respectively included in the packaging of this
14  * file.
15  */
16 
17 #ifndef __STDC_LIMIT_MACROS
18 # define __STDC_LIMIT_MACROS
19 #endif
20 #ifndef __STDC_CONSTANT_MACROS
21 # define __STDC_CONSTANT_MACROS
22 #endif
23 
24 #include <stdarg.h>
25 #include <inttypes.h>
26 
27 #import "OFObject.h"
28 #import "OFSerialization.h"
29 #import "OFJSONRepresentation.h"
30 #import "OFMessagePackRepresentation.h"
31 
32 OF_ASSUME_NONNULL_BEGIN
33 
36 @class OFConstantString;
37 
38 #if defined(__cplusplus) && __cplusplus >= 201103L
39 typedef char16_t of_char16_t;
40 typedef char32_t of_char32_t;
41 #else
42 typedef uint_least16_t of_char16_t;
43 typedef uint_least32_t of_char32_t;
44 #endif
45 typedef of_char32_t of_unichar_t;
46 
50 typedef enum of_string_encoding_t {
66 
67 enum {
68  OF_STRING_SEARCH_BACKWARDS = 1,
69  OF_STRING_SKIP_EMPTY = 2
70 };
71 
72 #ifdef OF_HAVE_BLOCKS
73 
80 typedef void (^of_string_line_enumeration_block_t)(OFString *line, bool *stop);
81 #endif
82 
83 @class OFArray OF_GENERIC(ObjectType);
84 @class OFURL;
85 
93 #ifdef OF_HAVE_PROPERTIES
94 @property (readonly) size_t length;
95 #endif
96 
102 + (instancetype)string;
103 
110 + (instancetype)stringWithUTF8String: (const char*)UTF8String;
111 
120 + (instancetype)stringWithUTF8String: (const char*)UTF8String
121  length: (size_t)UTF8StringLength;
122 
132 + (instancetype)stringWithUTF8StringNoCopy: (char*)UTF8String
133  freeWhenDone: (bool)freeWhenDone;
134 
142 + (instancetype)stringWithCString: (const char*)cString
143  encoding: (of_string_encoding_t)encoding;
144 
154 + (instancetype)stringWithCString: (const char*)cString
155  encoding: (of_string_encoding_t)encoding
156  length: (size_t)cStringLength;
157 
164 + (instancetype)stringWithString: (OFString*)string;
165 
174 + (instancetype)stringWithCharacters: (const of_unichar_t*)characters
175  length: (size_t)length;
176 
183 + (instancetype)stringWithUTF16String: (const of_char16_t*)string;
184 
193 + (instancetype)stringWithUTF16String: (const of_char16_t*)string
194  length: (size_t)length;
195 
204 + (instancetype)stringWithUTF16String: (const of_char16_t*)string
205  byteOrder: (of_byte_order_t)byteOrder;
206 
217 + (instancetype)stringWithUTF16String: (const of_char16_t*)string
218  length: (size_t)length
219  byteOrder: (of_byte_order_t)byteOrder;
220 
227 + (instancetype)stringWithUTF32String: (const of_char32_t*)string;
228 
237 + (instancetype)stringWithUTF32String: (const of_char32_t*)string
238  length: (size_t)length;
239 
248 + (instancetype)stringWithUTF32String: (const of_char32_t*)string
249  byteOrder: (of_byte_order_t)byteOrder;
250 
261 + (instancetype)stringWithUTF32String: (const of_char32_t*)string
262  length: (size_t)length
263  byteOrder: (of_byte_order_t)byteOrder;
264 
274 + (instancetype)stringWithFormat: (OFConstantString*)format, ...;
275 
276 #ifdef OF_HAVE_FILES
277 
284 + (instancetype)stringWithContentsOfFile: (OFString*)path;
285 
294 + (instancetype)stringWithContentsOfFile: (OFString*)path
295  encoding: (of_string_encoding_t)encoding;
296 #endif
297 
298 #if defined(OF_HAVE_FILES) || defined(OF_HAVE_SOCKETS)
299 
311 + (instancetype)stringWithContentsOfURL: (OFURL*)URL;
312 
321 + (instancetype)stringWithContentsOfURL: (OFURL*)URL
322  encoding: (of_string_encoding_t)encoding;
323 #endif
324 
331 + (OFString*)pathWithComponents: (OFArray OF_GENERIC(OFString*)*)components;
332 
340 - initWithUTF8String: (const char*)UTF8String;
341 
350 - initWithUTF8String: (const char*)UTF8String
351  length: (size_t)UTF8StringLength;
352 
364 - initWithUTF8StringNoCopy: (char*)UTF8String
365  freeWhenDone: (bool)freeWhenDone;
366 
375 - initWithCString: (const char*)cString
376  encoding: (of_string_encoding_t)encoding;
377 
387 - initWithCString: (const char*)cString
388  encoding: (of_string_encoding_t)encoding
389  length: (size_t)cStringLength;
390 
397 - initWithString: (OFString*)string;
398 
407 - initWithCharacters: (const of_unichar_t*)characters
408  length: (size_t)length;
409 
416 - initWithUTF16String: (const of_char16_t*)string;
417 
426 - initWithUTF16String: (const of_char16_t*)string
427  length: (size_t)length;
428 
437 - initWithUTF16String: (const of_char16_t*)string
438  byteOrder: (of_byte_order_t)byteOrder;
439 
450 - initWithUTF16String: (const of_char16_t*)string
451  length: (size_t)length
452  byteOrder: (of_byte_order_t)byteOrder;
453 
460 - initWithUTF32String: (const of_char32_t*)string;
461 
470 - initWithUTF32String: (const of_char32_t*)string
471  length: (size_t)length;
472 
481 - initWithUTF32String: (const of_char32_t*)string
482  byteOrder: (of_byte_order_t)byteOrder;
483 
494 - initWithUTF32String: (const of_char32_t*)string
495  length: (size_t)length
496  byteOrder: (of_byte_order_t)byteOrder;
497 
507 - initWithFormat: (OFConstantString*)format, ...;
508 
519 - initWithFormat: (OFConstantString*)format
520  arguments: (va_list)arguments;
521 
522 #ifdef OF_HAVE_FILES
523 
530 - initWithContentsOfFile: (OFString*)path;
531 
540 - initWithContentsOfFile: (OFString*)path
541  encoding: (of_string_encoding_t)encoding;
542 #endif
543 
544 #if defined(OF_HAVE_FILES) || defined(OF_HAVE_SOCKETS)
545 
558 - initWithContentsOfURL: (OFURL*)URL;
559 
568 - initWithContentsOfURL: (OFURL*)URL
569  encoding: (of_string_encoding_t)encoding;
570 #endif
571 
583 - (size_t)getCString: (char*)cString
584  maxLength: (size_t)maxLength
585  encoding: (of_string_encoding_t)encoding;
586 
599 - (size_t)getLossyCString: (char*)cString
600  maxLength: (size_t)maxLength
601  encoding: (of_string_encoding_t)encoding;
602 
613 - (const char*)cStringWithEncoding: (of_string_encoding_t)encoding
614  OF_RETURNS_INNER_POINTER;
615 
628 - (const char*)lossyCStringWithEncoding: (of_string_encoding_t)encoding
629  OF_RETURNS_INNER_POINTER;
630 
640 - (const char*)UTF8String OF_RETURNS_INNER_POINTER;
641 
647 - (size_t)length;
648 
656 - (size_t)cStringLengthWithEncoding: (of_string_encoding_t)encoding;
657 
663 - (size_t)UTF8StringLength;
664 
672 - (of_comparison_result_t)caseInsensitiveCompare: (OFString*)otherString;
673 
680 - (of_unichar_t)characterAtIndex: (size_t)index;
681 
689 - (void)getCharacters: (of_unichar_t*)buffer
690  inRange: (of_range_t)range;
691 
699 - (of_range_t)rangeOfString: (OFString*)string;
700 
713 - (of_range_t)rangeOfString: (OFString*)string
714  options: (int)options;
715 
729 - (of_range_t)rangeOfString: (OFString*)string
730  options: (int)options
731  range: (of_range_t)range;
732 
739 - (bool)containsString: (OFString*)string;
740 
747 - (OFString*)substringWithRange: (of_range_t)range;
748 
755 - (OFString*)stringByAppendingString: (OFString*)string;
756 
763 - (OFString*)stringByAppendingFormat: (OFConstantString*)format, ...;
764 
772 - (OFString*)stringByAppendingFormat: (OFConstantString*)format
773  arguments: (va_list)arguments;
774 
781 - (OFString*)stringByAppendingPathComponent: (OFString*)component;
782 
789 - (OFString*)stringByPrependingString: (OFString*)string;
790 
799 - (OFString*)stringByReplacingOccurrencesOfString: (OFString*)string
800  withString: (OFString*)replacement;
801 
814 - (OFString*)stringByReplacingOccurrencesOfString: (OFString*)string
815  withString: (OFString*)replacement
816  options: (int)options
817  range: (of_range_t)range;
818 
825 
832 
843 
850 
857 
865 
872 - (bool)hasPrefix: (OFString*)prefix;
873 
880 - (bool)hasSuffix: (OFString*)suffix;
881 
888 - (OFArray OF_GENERIC(OFString*)*)componentsSeparatedByString:
889  (OFString*)delimiter;
890 
902 - (OFArray OF_GENERIC(OFString*)*)
903  componentsSeparatedByString: (OFString*)delimiter
904  options: (int)options;
905 
911 - (OFArray OF_GENERIC(OFString*)*)pathComponents;
912 
919 
926 
933 
940 
947 
957 
971 - (intmax_t)decimalValue;
972 
986 - (uintmax_t)hexadecimalValue;
987 
996 - (float)floatValue;
997 
1006 - (double)doubleValue;
1007 
1017 - (const of_unichar_t*)characters OF_RETURNS_INNER_POINTER;
1018 
1028 - (const of_char16_t*)UTF16String OF_RETURNS_INNER_POINTER;
1029 
1040 - (const of_char16_t*)UTF16StringWithByteOrder: (of_byte_order_t)byteOrder
1041  OF_RETURNS_INNER_POINTER;
1042 
1048 - (size_t)UTF16StringLength;
1049 
1059 - (const of_char32_t*)UTF32String OF_RETURNS_INNER_POINTER;
1060 
1071 - (const of_char32_t*)UTF32StringWithByteOrder: (of_byte_order_t)byteOrder
1072  OF_RETURNS_INNER_POINTER;
1073 
1074 #ifdef OF_HAVE_FILES
1075 
1080 - (void)writeToFile: (OFString*)path;
1081 
1089 - (void)writeToFile: (OFString*)path
1090  encoding: (of_string_encoding_t)encoding;
1091 #endif
1092 
1093 #ifdef OF_HAVE_BLOCKS
1094 
1099 - (void)enumerateLinesUsingBlock: (of_string_line_enumeration_block_t)block;
1100 #endif
1101 @end
1102 
1103 #ifdef __cplusplus
1104 extern "C" {
1105 #endif
1106 extern size_t of_string_utf8_encode(of_unichar_t, char*);
1107 extern size_t of_string_utf8_decode(const char*, size_t, of_unichar_t*);
1108 extern size_t of_string_utf16_length(const of_char16_t*);
1109 extern size_t of_string_utf32_length(const of_char32_t*);
1110 #ifdef __cplusplus
1111 }
1112 #endif
1113 
1114 OF_ASSUME_NONNULL_END
1115 
1116 #import "OFConstantString.h"
1117 #import "OFMutableString.h"
1118 #import "OFString+Hashing.h"
1119 #import "OFString+JSONValue.h"
1120 #import "OFString+Serialization.h"
1121 #import "OFString+URLEncoding.h"
1122 #import "OFString+XMLEscaping.h"
1123 #import "OFString+XMLUnescaping.h"
1124 
1125 #ifndef NSINTEGER_DEFINED
1126 /*
1127  * Very *ugly* hack required for string boxing literals to work.
1128  *
1129  * This hack is needed in order to work with `@class NSString` from Apple's
1130  * objc/NSString.h - which is included when using modules - as
1131  * @compatibility_alias does not work if @class has been used before.
1132  * For some reason, this makes Clang refer to OFString for string box literals
1133  * and not to NSString (which would result in a linker error, but would be the
1134  * correct behavior).
1135  *
1136  * TODO: Submit a patch for Clang that makes the boxing classes configurable!
1137  */
1138 @interface NSString: OFString
1139 @end
1140 #endif
A protocol for serializing objects.
Definition: OFSerialization.h:30
double doubleValue()
Returns the double value of the string as a double.
Definition: OFString.m:2287
size_t UTF16StringLength()
Returns the length of the string in UTF-16 characters.
Definition: OFString.m:2385
Definition: OFString.h:60
An abstract class for storing objects in an array.
Definition: OFArray.h:95
of_string_encoding_t
The encoding of a string.
Definition: OFString.h:50
OFArray OF_GENERIC(OFString * pathComponents()
Returns the components of the path.
Definition: OFString.m:1953
OFString * lastPathComponent()
Returns the last component of the path.
Definition: OFString.m:1990
A protocol for comparing objects.
Definition: OFObject.h:933
of_byte_order_t
An enum for storing endianess.
Definition: OFObject.h:53
uintmax_t hexadecimalValue()
Returns the hexadecimal value of the string as an uintmax_t.
Definition: OFString.m:2193
Definition: OFString.h:64
A class for storing constant strings using the @"" literal.
Definition: OFConstantString.h:37
The root class for all other classes inside ObjFW.
Definition: OFObject.h:364
OFString * stringByStandardizingPath()
Returns the path with relative sub paths resolved.
Definition: OFString.m:2125
intmax_t decimalValue()
Returns the decimal value of the string as an intmax_t.
Definition: OFString.m:2138
OFString * stringByDeletingEnclosingWhitespaces()
Creates a new string by deleting leading and trailing whitespaces.
Definition: OFString.m:1824
const of_char32_t * UTF32String()
Returns the string in UTF-32 encoding with native byte order.
Definition: OFString.m:2399
const of_char16_t * UTF16String()
Returns the string in UTF-16 encoding with native byte order.
Definition: OFString.m:2327
Definition: OFString.h:62
A protocol implemented by classes that support encoding to a JSON representation. ...
Definition: OFJSONRepresentation.h:38
A class for handling strings.
Definition: OFString.h:91
Definition: OFString.h:56
const char * UTF8String()
Returns the OFString as a UTF-8 encoded C string.
Definition: OFString.m:1182
of_comparison_result_t
A result of a comparison.
Definition: OFObject.h:41
A protocol implemented by classes that support encoding to a MessagePack representation.
Definition: OFMessagePackRepresentation.h:30
void(^ of_string_line_enumeration_block_t)(OFString *line, bool *stop)
A block for enumerating the lines of a string.
Definition: OFString.h:80
OFString * stringByStandardizingURLPath()
Returns the URL path with relative sub paths resolved.
Definition: OFString.m:2132
Definition: OFString.h:58
Definition: OFString.h:52
A range.
Definition: OFObject.h:65
OFString * uppercaseString()
Returns the string in uppercase.
Definition: OFString.m:1769
size_t length()
Returns the length of the string in Unicode characters.
A protocol for the creation of mutable copies.
Definition: OFObject.h:917
A protocol for the creation of copies.
Definition: OFObject.h:896
const of_unichar_t * characters()
Returns the string as an array of Unicode characters.
Definition: OFString.m:2313
OFString * stringByDeletingLastPathComponent()
Returns the directory name of the path.
Definition: OFString.m:2055
OFString * capitalizedString()
Returns the string capitalized.
Definition: OFString.m:1791
size_t UTF8StringLength()
Returns the number of bytes the string needs in UTF-8 encoding.
Definition: OFString.m:1225
OFString * stringByDeletingLeadingWhitespaces()
Creates a new string by deleting leading whitespaces.
Definition: OFString.m:1802
Definition: OFString.h:54
A class for parsing URLs and accessing parts of it.
Definition: OFURL.h:29
OFString * lowercaseString()
Returns the string in lowercase.
Definition: OFString.m:1780
instancetype string()
Creates a new OFString.
Definition: OFString.m:505
float floatValue()
Returns the float value of the string as a float.
Definition: OFString.m:2261
OFString * stringByDeletingTrailingWhitespaces()
Creates a new string by deleting trailing whitespaces.
Definition: OFString.m:1813
OFString * pathExtension()
Returns the file extension of the path.
Definition: OFString.m:2035
OFString * stringByDeletingPathExtension()
Returns a new string with the file extension of the path removed.
Definition: OFString.m:2093