ObjFW  Check-in [e685b742d9]

Overview
Comment:Documentation improvements (add references).
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: e685b742d95b1d234118f7c07c42291dbe5db28c09008243fd9439f7adbc7460
User & Date: js on 2012-10-29 13:35:53
Other Links: manifest | tags
Context
2012-10-29
13:50
Increase library major version. check-in: ebed14967d user: js tags: trunk
13:35
Documentation improvements (add references). check-in: e685b742d9 user: js tags: trunk
13:03
Simplify seeking. check-in: dc1093e2a5 user: js tags: trunk
Changes

Modified src/OFCondition.h from [7903b725d1] to [cc3155f541].

29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
 * @brief Creates a new condition.
 *
 * @return A new, autoreleased OFCondition
 */
+ (instancetype)condition;

/*!
 * @brief Blocks the current thread until another thread calls -[signal] or
 *	  -[broadcast].
 */
- (void)wait;

/*!
 * @brief Signals the next waiting thread to continue.
 */
- (void)signal;







|
|







29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
 * @brief Creates a new condition.
 *
 * @return A new, autoreleased OFCondition
 */
+ (instancetype)condition;

/*!
 * @brief Blocks the current thread until another thread calls @ref signal or
 *	  @ref broadcast.
 */
- (void)wait;

/*!
 * @brief Signals the next waiting thread to continue.
 */
- (void)signal;

Modified src/OFDataArray.h from [c01f27a1bc] to [ebbd8162b6].

89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 *	  of the Base64-encoded string.
 *
 * @param string The string with the Base64-encoded data
 * @return A new autoreleased OFDataArray
 */
+ (instancetype)dataArrayWithBase64EncodedString: (OFString*)string;

/*!
 * @brief Initializes an already allocated OFDataArray with an item size of 1.
 *
 * @return A initialized OFDataArray
 */
- init;

/*!
 * @brief Initializes an already allocated OFDataArray whose items all have the
 *	  same size.
 *
 * @param itemSize The size of each element in the OFDataArray
 * @return An initialized OFDataArray
 */







<
<
<
<
<
<
<







89
90
91
92
93
94
95







96
97
98
99
100
101
102
 *	  of the Base64-encoded string.
 *
 * @param string The string with the Base64-encoded data
 * @return A new autoreleased OFDataArray
 */
+ (instancetype)dataArrayWithBase64EncodedString: (OFString*)string;








/*!
 * @brief Initializes an already allocated OFDataArray whose items all have the
 *	  same size.
 *
 * @param itemSize The size of each element in the OFDataArray
 * @return An initialized OFDataArray
 */
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
- initWithStringRepresentation: (OFString*)string;

/*!
 * @brief Initializes an already allocated OFDataArray with an item size of 1,
 *	  containing the data of the Base64-encoded string.
 *
 * @param string The string with the Base64-encoded data
 * @return A initialized OFDataArray
 */
- initWithBase64EncodedString: (OFString*)string;

/*!
 * @brief Returns the number of items in the OFDataArray.
 *
 * @return The number of items in the OFDataArray







|







130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
- initWithStringRepresentation: (OFString*)string;

/*!
 * @brief Initializes an already allocated OFDataArray with an item size of 1,
 *	  containing the data of the Base64-encoded string.
 *
 * @param string The string with the Base64-encoded data
 * @return An initialized OFDataArray
 */
- initWithBase64EncodedString: (OFString*)string;

/*!
 * @brief Returns the number of items in the OFDataArray.
 *
 * @return The number of items in the OFDataArray

Modified src/OFDate.h from [acf9da0e04] to [2d8613f05a].

52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
 */
+ (instancetype)dateWithTimeIntervalSinceNow: (double)seconds;

/*!
 * @brief Creates a new OFDate with the specified string in the specified
 *	  format.
 *
 * The time zone used is UTC. See +[dateWithLocalDateString:format:] if you
 * want local time.
 *
 * See the manpage for strftime for information on the format.
 *
 * @warning The format is currently limited to the following format specifiers:
 *	    %%d, %%e, %%H, %%m, %%M, %%S, %%y, %%Y, %%, %%n and %%t.
 *







|







52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
 */
+ (instancetype)dateWithTimeIntervalSinceNow: (double)seconds;

/*!
 * @brief Creates a new OFDate with the specified string in the specified
 *	  format.
 *
 * The time zone used is UTC. See @ref dateWithLocalDateString:format: if you
 * want local time.
 *
 * See the manpage for strftime for information on the format.
 *
 * @warning The format is currently limited to the following format specifiers:
 *	    %%d, %%e, %%H, %%m, %%M, %%S, %%y, %%Y, %%, %%n and %%t.
 *
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
- initWithTimeIntervalSinceNow: (double)seconds;

/*!
 * @brief Initializes an already allocated OFDate with the specified string in
 *	  the specified format.
 *
 * The time zone used is UTC. If a time zone is specified anyway, an
 * OFInvalidFormatException is thrown. See -[initWithLocalDateString:format:]
 * if you want to specify a time zone.
 *
 * See the manpage for strftime for information on the format.
 *
 * @warning The format is currently limited to the following format specifiers:
 *	    %%d, %%e, %%H, %%m, %%M, %%S, %%y, %%Y, %%, %%n and %%t.
 *







|







124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
- initWithTimeIntervalSinceNow: (double)seconds;

/*!
 * @brief Initializes an already allocated OFDate with the specified string in
 *	  the specified format.
 *
 * The time zone used is UTC. If a time zone is specified anyway, an
 * OFInvalidFormatException is thrown. See @ref initWithLocalDateString:format:
 * if you want to specify a time zone.
 *
 * See the manpage for strftime for information on the format.
 *
 * @warning The format is currently limited to the following format specifiers:
 *	    %%d, %%e, %%H, %%m, %%M, %%S, %%y, %%Y, %%, %%n and %%t.
 *

Modified src/OFDictionary.h from [300f9a46a5] to [d22e976267].

99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
 * @brief Creates a new OFDictionary with the specified keys objects.
 *
 * @param firstKey The first key
 * @return A new autoreleased OFDictionary
 */
+ (instancetype)dictionaryWithKeysAndObjects: (id)firstKey, ... OF_SENTINEL;

/*!
 * @brief Initializes an already allocated OFDictionary.
 *
 * @return An initialized OFDictionary
 */
- init;

/*!
 * @brief Initializes an already allocated OFDictionary with the specified
 *	  OFDictionary.
 *
 * @param dictionary An OFDictionary
 * @return An initialized OFDictionary
 */







<
<
<
<
<
<
<







99
100
101
102
103
104
105







106
107
108
109
110
111
112
 * @brief Creates a new OFDictionary with the specified keys objects.
 *
 * @param firstKey The first key
 * @return A new autoreleased OFDictionary
 */
+ (instancetype)dictionaryWithKeysAndObjects: (id)firstKey, ... OF_SENTINEL;








/*!
 * @brief Initializes an already allocated OFDictionary with the specified
 *	  OFDictionary.
 *
 * @param dictionary An OFDictionary
 * @return An initialized OFDictionary
 */

Modified src/OFObject.h from [97ec10457b] to [856cc09e65].

368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
 * OFAllocFailedException.
 *
 * @return The allocated object
 */
+ alloc;

/*!
 * @brief Allocates memory for a new instance and calls -[init] on it.
 * @return An allocated and initialized object
 */
+ new;

/*!
 * @brief Returns the class.
 *







|







368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
 * OFAllocFailedException.
 *
 * @return The allocated object
 */
+ alloc;

/*!
 * @brief Allocates memory for a new instance and calls @ref init on it.
 * @return An allocated and initialized object
 */
+ new;

/*!
 * @brief Returns the class.
 *
544
545
546
547
548
549
550
551



552
553

554
555
556
557
558
559
560
 * @return Whether the method has been added to the class
 */
+ (BOOL)resolveInstanceMethod: (SEL)selector;

/*!
 * @brief Initializes an already allocated object.
 *
 * Derived classes may override this, but need to do self = [super init] before



 * they do any initialization themselves. init may never return nil, instead
 * an exception (for example OFInitializationFailed) should be thrown.

 *
 * @return An initialized object
 */
- init;

/*!
 * @brief Returns the name of the object's class.







|
>
>
>
|
|
>







544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
 * @return Whether the method has been added to the class
 */
+ (BOOL)resolveInstanceMethod: (SEL)selector;

/*!
 * @brief Initializes an already allocated object.
 *
 * Derived classes may override this, but need to do
 * @code
 *   self = [super init]
 * @endcode
 * before they do any initialization themselves. @ref init may never return nil,
 * instead an exception (for example OFInitializationFailedException) should be
 * thrown.
 *
 * @return An initialized object
 */
- init;

/*!
 * @brief Returns the name of the object's class.

Modified src/OFStream.h from [16acb784a6] to [c7b337bee8].

43
44
45
46
47
48
49
50

51
52
53
54
55
56
57
58
59
60
61
62
 * @warning Even though the OFCopying protocol is implemented, it does
 *	    <i>not</i> return an independent copy of the stream, but instead
 *	    retains it. This is so that the stream can be used as a key for a
 *	    dictionary, so context can be associated with a stream. Using a
 *	    stream in more than one thread at the same time is not thread-safe,
 *	    even if copy was called to create one "instance" for every thread!
 *
 * @note If you want to subclass this, override lowlevelReadIntoBuffer:length:,

 *	 lowlevelWriteBuffer:length: and lowlevelIsAtEndOfStream, but nothing
 *	 else, as those are are the methods that do the actual work. OFStream
 *	 uses those for all other methods and does all the caching and other
 *	 stuff for you. If you override these methods without the lowlevel
 *	 prefix, you <i>will</i> break caching and get broken results!
 */
@interface OFStream: OFObject <OFCopying>
{
	char   *cache;
	char   *writeBuffer;
	size_t cacheLength, writeBufferLength;
	BOOL   writeBufferEnabled;







|
>
|
|
|
|
|







43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
 * @warning Even though the OFCopying protocol is implemented, it does
 *	    <i>not</i> return an independent copy of the stream, but instead
 *	    retains it. This is so that the stream can be used as a key for a
 *	    dictionary, so context can be associated with a stream. Using a
 *	    stream in more than one thread at the same time is not thread-safe,
 *	    even if copy was called to create one "instance" for every thread!
 *
 * @note If you want to subclass this, override
 *	 @ref lowlevelReadIntoBuffer:length:, @ref lowlevelWriteBuffer:length:
 *	 and @ref lowlevelIsAtEndOfStream, but nothing else, as those are are
 *	 the methods that do the actual work. OFStream uses those for all other
 *	 methods and does all the caching and other stuff for you. If you
 *	 override these methods without the lowlevel prefix, you <i>will</i>
 *	 break caching and get broken results!
 */
@interface OFStream: OFObject <OFCopying>
{
	char   *cache;
	char   *writeBuffer;
	size_t cacheLength, writeBufferLength;
	BOOL   writeBufferEnabled;
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
- (BOOL)isAtEndOfStream;

/*!
 * @brief Reads <i>at most</i> size bytes from the stream into a buffer.
 *
 * On network streams, this might read less than the specified number of bytes.
 * If you want to read exactly the specified number of bytes, use
 * -readIntoBuffer:exactLength:. Note that a read can even return 0 bytes -
 * this does not necessarily mean that the stream ended, so you still need to
 * check isAtEndOfStream.
 *
 * @param buffer The buffer into which the data is read
 * @param length The length of the data that should be read at most.
 *		 The buffer <i>must</i> be at least this big!
 * @return The number of bytes read
 */
- (size_t)readIntoBuffer: (void*)buffer
		  length: (size_t)length;

/*!
 * @brief Reads exactly the specified length bytes from the stream into a
 *	  buffer.
 *
 * Unlike readIntoBuffer:length:, this method does not return when less than the
 * specified length has been read - instead, it waits until it got exactly the
 * specified length.
 *
 * @warning Only call this when you know that specified amount of data is
 *	    available! Otherwise you will get an exception!
 *
 * @param buffer The buffer into which the data is read
 * @param length The length of the data that should be read.
 *		 The buffer <i>must</i> be <i>exactly</i> this big!
 */
 - (void)readIntoBuffer: (void*)buffer
	    exactLength: (size_t)length;

/*!
 * @brief Asyncronously reads <i>at most</i> size bytes from the stream into a
 *	  buffer.
 *
 * On network streams, this might read less than the specified number of bytes.
 * If you want to read exactly the specified number of bytes, use
 * asyncReadIntoBuffer:exactLength:block:. Note that a read can even return 0
 * bytes - this does not necessarily mean that the stream ended, so you still
 * need to check isAtEndOfStream.
 *
 * @param buffer The buffer into which the data is read.
 *		 The buffer must not be free'd before the async read completed!
 * @param length The length of the data that should be read at most.
 *		 The buffer <i>must</i> be at least this big!
 * @param target The target on which the selector should be called when the
 *		 data has been received. If the method returns YES, it will be







|

|













|
|
|

















|
|
|







78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
- (BOOL)isAtEndOfStream;

/*!
 * @brief Reads <i>at most</i> size bytes from the stream into a buffer.
 *
 * On network streams, this might read less than the specified number of bytes.
 * If you want to read exactly the specified number of bytes, use
 * @ref readIntoBuffer:exactLength:. Note that a read can even return 0 bytes -
 * this does not necessarily mean that the stream ended, so you still need to
 * check @ref isAtEndOfStream.
 *
 * @param buffer The buffer into which the data is read
 * @param length The length of the data that should be read at most.
 *		 The buffer <i>must</i> be at least this big!
 * @return The number of bytes read
 */
- (size_t)readIntoBuffer: (void*)buffer
		  length: (size_t)length;

/*!
 * @brief Reads exactly the specified length bytes from the stream into a
 *	  buffer.
 *
 * Unlike @ref readIntoBuffer:length:, this method does not return when less
 * than the specified length has been read - instead, it waits until it got
 * exactly the specified length.
 *
 * @warning Only call this when you know that specified amount of data is
 *	    available! Otherwise you will get an exception!
 *
 * @param buffer The buffer into which the data is read
 * @param length The length of the data that should be read.
 *		 The buffer <i>must</i> be <i>exactly</i> this big!
 */
 - (void)readIntoBuffer: (void*)buffer
	    exactLength: (size_t)length;

/*!
 * @brief Asyncronously reads <i>at most</i> size bytes from the stream into a
 *	  buffer.
 *
 * On network streams, this might read less than the specified number of bytes.
 * If you want to read exactly the specified number of bytes, use
 * @ref asyncReadIntoBuffer:exactLength:block:. Note that a read can even
 * return 0 bytes - this does not necessarily mean that the stream ended, so
 * you still need to check @ref isAtEndOfStream.
 *
 * @param buffer The buffer into which the data is read.
 *		 The buffer must not be free'd before the async read completed!
 * @param length The length of the data that should be read at most.
 *		 The buffer <i>must</i> be at least this big!
 * @param target The target on which the selector should be called when the
 *		 data has been received. If the method returns YES, it will be
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
		     target: (id)target
		   selector: (SEL)selector;

/*!
 * @brief Asyncronously reads exactly the specified length bytes from the
 *	  stream into a buffer.
 *
 * Unlike asyncReadIntoBuffer:length:block, this method does not call the
 * method when less than the specified length has been read - instead, it waits
 * until it got exactly the specified length, the stream has ended or an
 * exception occurred.
 *
 * @param buffer The buffer into which the data is read
 * @param length The length of the data that should be read.
 *		 The buffer <i>must</i> be <i>exactly</i> this big!







|







141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
		     target: (id)target
		   selector: (SEL)selector;

/*!
 * @brief Asyncronously reads exactly the specified length bytes from the
 *	  stream into a buffer.
 *
 * Unlike @ref asyncReadIntoBuffer:length:block, this method does not call the
 * method when less than the specified length has been read - instead, it waits
 * until it got exactly the specified length, the stream has ended or an
 * exception occurred.
 *
 * @param buffer The buffer into which the data is read
 * @param length The length of the data that should be read.
 *		 The buffer <i>must</i> be <i>exactly</i> this big!
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
#ifdef OF_HAVE_BLOCKS
/*!
 * @brief Asyncronously reads <i>at most</i> size bytes from the stream into a
 *	  buffer.
 *
 * On network streams, this might read less than the specified number of bytes.
 * If you want to read exactly the specified number of bytes, use
 * asyncReadIntoBuffer:exactLength:block:. Note that a read can even return 0
 * bytes - this does not necessarily mean that the stream ended, so you still
 * need to check isAtEndOfStream.
 *
 * @param buffer The buffer into which the data is read.
 *		 The buffer must not be free'd before the async read completed!
 * @param length The length of the data that should be read at most.
 *		 The buffer <i>must</i> be at least this big!
 * @param block The block to call when the data has been received.
 *		If the block returns YES, it will be called again with the same
 *		buffer and maximum length when more data has been received. If
 *		you want the next block in the queue to handle the data
 *		received next, you need to return NO from the block.
 */
- (void)asyncReadIntoBuffer: (void*)buffer
		     length: (size_t)length
		      block: (of_stream_async_read_block_t)block;

/*!
 * @brief Asyncronously reads exactly the specified length bytes from the
 *	  stream into a buffer.
 *
 * Unlike asyncReadIntoBuffer:length:block, this method does not invoke the
 * block when less than the specified length has been read - instead, it waits
 * until it got exactly the specified length, the stream has ended or an
 * exception occurred.
 *
 * @param buffer The buffer into which the data is read
 * @param length The length of the data that should be read.
 *		 The buffer <i>must</i> be <i>exactly</i> this big!







|
|
|



















|







171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
#ifdef OF_HAVE_BLOCKS
/*!
 * @brief Asyncronously reads <i>at most</i> size bytes from the stream into a
 *	  buffer.
 *
 * On network streams, this might read less than the specified number of bytes.
 * If you want to read exactly the specified number of bytes, use
 * @ref asyncReadIntoBuffer:exactLength:block:. Note that a read can even
 * return 0 bytes - this does not necessarily mean that the stream ended, so
 * you still need to check @ref isAtEndOfStream.
 *
 * @param buffer The buffer into which the data is read.
 *		 The buffer must not be free'd before the async read completed!
 * @param length The length of the data that should be read at most.
 *		 The buffer <i>must</i> be at least this big!
 * @param block The block to call when the data has been received.
 *		If the block returns YES, it will be called again with the same
 *		buffer and maximum length when more data has been received. If
 *		you want the next block in the queue to handle the data
 *		received next, you need to return NO from the block.
 */
- (void)asyncReadIntoBuffer: (void*)buffer
		     length: (size_t)length
		      block: (of_stream_async_read_block_t)block;

/*!
 * @brief Asyncronously reads exactly the specified length bytes from the
 *	  stream into a buffer.
 *
 * Unlike @ref asyncReadIntoBuffer:length:block, this method does not invoke the
 * block when less than the specified length has been read - instead, it waits
 * until it got exactly the specified length, the stream has ended or an
 * exception occurred.
 *
 * @param buffer The buffer into which the data is read
 * @param length The length of the data that should be read.
 *		 The buffer <i>must</i> be <i>exactly</i> this big!
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
 * @return The line that was read, autoreleased, or nil if the line is not
 *	   complete yet
 */
- (OFString*)tryReadLine;

/*!
 * @brief Tries to read a line from the stream with the specified encoding (see
 *	  readLineWithEncoding:) and returns nil if no complete line has been
 *	  received yet.
 *
 * @param encoding The encoding used by the stream
 * @return The line that was read, autoreleased, or nil if the line is not
 *	   complete yet
 */
- (OFString*)tryReadLineWithEncoding: (of_string_encoding_t)encoding;








|
|







629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
 * @return The line that was read, autoreleased, or nil if the line is not
 *	   complete yet
 */
- (OFString*)tryReadLine;

/*!
 * @brief Tries to read a line from the stream with the specified encoding (see
 *	  @ref readLineWithEncoding:) and returns nil if no complete line has
 *	  been received yet.
 *
 * @param encoding The encoding used by the stream
 * @return The line that was read, autoreleased, or nil if the line is not
 *	   complete yet
 */
- (OFString*)tryReadLineWithEncoding: (of_string_encoding_t)encoding;

661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
 *	   stream has been reached.
 */
- (OFString*)readTillDelimiter: (OFString*)delimiter
		      encoding: (of_string_encoding_t)encoding;

/*!
 * @brief Tries to reads until the specified string or \\0 is found or the end
 *	  of stream (see readTillDelimiter:) and returns nil if not enough data
 *	  has been received yet.
 *
 * @param delimiter The delimiter
 * @return The line that was read, autoreleased, or nil if the end of the
 *	   stream has been reached.
 */
- (OFString*)tryReadTillDelimiter: (OFString*)delimiter;

/*!
 * @brief Tries to read until the specified string or \\0 is found or the end
 *	  of stream occurs (see readTIllDelimiterWithEncoding:) and returns nil
 *	  if not enough data has been received yet.
 *
 * @param delimiter The delimiter
 * @param encoding The encoding used by the stream
 * @return The line that was read, autoreleased, or nil if the end of the
 *	   stream has been reached.
 */
- (OFString*)tryReadTillDelimiter: (OFString*)delimiter







|
|









|
|







662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
 *	   stream has been reached.
 */
- (OFString*)readTillDelimiter: (OFString*)delimiter
		      encoding: (of_string_encoding_t)encoding;

/*!
 * @brief Tries to reads until the specified string or \\0 is found or the end
 *	  of stream (see @ref readTillDelimiter:) and returns nil if not enough
 *	  data has been received yet.
 *
 * @param delimiter The delimiter
 * @return The line that was read, autoreleased, or nil if the end of the
 *	   stream has been reached.
 */
- (OFString*)tryReadTillDelimiter: (OFString*)delimiter;

/*!
 * @brief Tries to read until the specified string or \\0 is found or the end
 *	  of stream occurs (see @ref readTillDelimiterWithEncoding:) and
 *	  returns nil if not enough data has been received yet.
 *
 * @param delimiter The delimiter
 * @param encoding The encoding used by the stream
 * @return The line that was read, autoreleased, or nil if the end of the
 *	   stream has been reached.
 */
- (OFString*)tryReadTillDelimiter: (OFString*)delimiter

Modified src/OFStreamObserver.h from [714bdc609e] to [fa395911d4].

41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
#endif
#ifdef OF_HAVE_OPTIONAL_PROTOCOLS
@optional
#endif
/*!
 * @brief This callback is called when a stream did get ready for reading.
 *
 * NOTE: When -[tryReadLine] or -[tryReadTillDelimiter:] has been called on the
 *	 the stream, this callback will not be called again until new data has
 *	 been received, even though there is still data in the cache. The reason
 *	 for this is to prevent spinning in a loop when there is an incomplete
 *	 string in the cache. Once the string is complete, the callback will be
 *	 called again if there is data in the cache.
 *
 * @param stream The stream which did become ready for reading







|







41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
#endif
#ifdef OF_HAVE_OPTIONAL_PROTOCOLS
@optional
#endif
/*!
 * @brief This callback is called when a stream did get ready for reading.
 *
 * @note When @ref tryReadLine or @ref tryReadTillDelimiter: has been called on
 *	 the stream, this callback will not be called again until new data has
 *	 been received, even though there is still data in the cache. The reason
 *	 for this is to prevent spinning in a loop when there is an incomplete
 *	 string in the cache. Once the string is complete, the callback will be
 *	 called again if there is data in the cache.
 *
 * @param stream The stream which did become ready for reading
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
 */
- (void)streamDidReceiveException: (OFStream*)stream;
@end

/*!
 * @brief A class that can observe multiple streams at once.
 *
 * Note: Currently, Win32 can only observe sockets and not files!
 */
@interface OFStreamObserver: OFObject
{
	OFMutableArray *readStreams;
	OFMutableArray *writeStreams;
	__unsafe_unretained OFStream **FDToStream;
	size_t maxFD;







|







70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
 */
- (void)streamDidReceiveException: (OFStream*)stream;
@end

/*!
 * @brief A class that can observe multiple streams at once.
 *
 * @note Currently, Win32 can only observe sockets and not files!
 */
@interface OFStreamObserver: OFObject
{
	OFMutableArray *readStreams;
	OFMutableArray *writeStreams;
	__unsafe_unretained OFStream **FDToStream;
	size_t maxFD;
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 * @brief Adds a stream to observe for reading.
 *
 * This is also used to observe a listening socket for incoming connections,
 * which then triggers a read event for the observed stream.
 *
 * It is recommended that the stream you add is set to non-blocking mode.
 *
 * If there is an -[observe] call blocking, it will be canceled. The reason for
 * this is to prevent blocking even though the new added stream is ready.
 *
 * @param stream The stream to observe for reading
 */
- (void)addStreamForReading: (OFStream*)stream;

/*!
 * @brief Adds a stream to observe for writing.
 *
 * It is recommended that the stream you add is set to non-blocking mode.
 *
 * If there is an -[observe] call blocking, it will be canceled. The reason for
 * this is to prevent blocking even though the new added stream is ready.
 *
 * @param stream The stream to observe for writing
 */
- (void)addStreamForWriting: (OFStream*)stream;

/*!
 * @brief Removes a stream to observe for reading.
 *
 * If there is an -[observe] call blocking, it will be canceled. The reason for
 * this is to prevent the removed stream from still being observed.
 *
 * @param stream The stream to remove from observing for reading
 */
- (void)removeStreamForReading: (OFStream*)stream;

/*!
 * @brief Removes a stream to observe for writing.
 *
 * If there is an -[observe] call blocking, it will be canceled. The reason for
 * this is to prevent the removed stream from still being observed.
 *
 * @param stream The stream to remove from observing for writing
 */
- (void)removeStreamForWriting: (OFStream*)stream;

/*!
 * @brief Observes all streams and blocks until an event happens on a stream.







|
|










|
|








|
|








|
|







121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 * @brief Adds a stream to observe for reading.
 *
 * This is also used to observe a listening socket for incoming connections,
 * which then triggers a read event for the observed stream.
 *
 * It is recommended that the stream you add is set to non-blocking mode.
 *
 * If there is an @ref observe call blocking, it will be canceled. The reason
 * for this is to prevent blocking even though the new added stream is ready.
 *
 * @param stream The stream to observe for reading
 */
- (void)addStreamForReading: (OFStream*)stream;

/*!
 * @brief Adds a stream to observe for writing.
 *
 * It is recommended that the stream you add is set to non-blocking mode.
 *
 * If there is an @ref observe call blocking, it will be canceled. The reason
 * for this is to prevent blocking even though the new added stream is ready.
 *
 * @param stream The stream to observe for writing
 */
- (void)addStreamForWriting: (OFStream*)stream;

/*!
 * @brief Removes a stream to observe for reading.
 *
 * If there is an @ref observe call blocking, it will be canceled. The reason
 * for this is to prevent the removed stream from still being observed.
 *
 * @param stream The stream to remove from observing for reading
 */
- (void)removeStreamForReading: (OFStream*)stream;

/*!
 * @brief Removes a stream to observe for writing.
 *
 * If there is an @ref observe call blocking, it will be canceled. The reason
 * for this is to prevent the removed stream from still being observed.
 *
 * @param stream The stream to remove from observing for writing
 */
- (void)removeStreamForWriting: (OFStream*)stream;

/*!
 * @brief Observes all streams and blocks until an event happens on a stream.

Modified src/OFString+JSONValue.h from [90f09f4010] to [5e2364c7d7].

34
35
36
37
38
39
40
41
42
43
44
45
46
 * @warning Although not specified by the JSON specification, this can also
 *          return primitives like strings and numbers. The rationale behind
 *          this is that most JSON parsers allow JSON data just consisting of a
 *          single primitive, leading to realworld JSON files sometimes only
 *          consisting of a single primitive. Therefore, you should not make any
 *          assumptions about the object returned by this method if you don't
 *          want your program to terminate due to a message not understood, but
 *          instead check the returned object using -[isKindOfClass:].
 *
 * @return An object
 */
- (id)JSONValue;
@end







|





34
35
36
37
38
39
40
41
42
43
44
45
46
 * @warning Although not specified by the JSON specification, this can also
 *          return primitives like strings and numbers. The rationale behind
 *          this is that most JSON parsers allow JSON data just consisting of a
 *          single primitive, leading to realworld JSON files sometimes only
 *          consisting of a single primitive. Therefore, you should not make any
 *          assumptions about the object returned by this method if you don't
 *          want your program to terminate due to a message not understood, but
 *          instead check the returned object using @ref isKindOfClass:.
 *
 * @return An object
 */
- (id)JSONValue;
@end

Modified src/OFString+XMLUnescaping.h from [0af39e8a26] to [3d3fa06f14].

21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
#endif
extern int _OFString_XMLUnescaping_reference;
#ifdef __cplusplus
}
#endif

#ifdef OF_HAVE_BLOCKS
typedef OFString* (^of_string_xml_unescaping_block_t)(OFString *str,
    OFString *entity);
#endif

/*!
 * @brief A protocol that needs to be implemented by delegates for
 *	  -[stringByXMLUnescapingWithHandler:].
 */
@protocol OFStringXMLUnescapingDelegate <OFObject>
/*!
 * @brief This callback is called when an unknown entity was found while trying
 *	  to unescape XML.
 *
 * The callback is supposed to return a substitution for the entity or nil if
 * it is unknown to the callback as well, in which case an exception will be
 * thrown.
 *
 * @param str The string which contains the unknown entity
 * @param entity The name of the entity that is unknown
 * @return A substitution for the entity or nil
 */
-	   (OFString*)string: (OFString*)str
  containsUnknownEntityNamed: (OFString*)entity;
@end

/*!
 * @brief A category for unescaping XML in strings.
 */
@interface OFString (XMLUnescaping)







|





|










|



|







21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
#endif
extern int _OFString_XMLUnescaping_reference;
#ifdef __cplusplus
}
#endif

#ifdef OF_HAVE_BLOCKS
typedef OFString* (^of_string_xml_unescaping_block_t)(OFString *string,
    OFString *entity);
#endif

/*!
 * @brief A protocol that needs to be implemented by delegates for
 *	  stringByXMLUnescapingWithHandler:.
 */
@protocol OFStringXMLUnescapingDelegate <OFObject>
/*!
 * @brief This callback is called when an unknown entity was found while trying
 *	  to unescape XML.
 *
 * The callback is supposed to return a substitution for the entity or nil if
 * it is unknown to the callback as well, in which case an exception will be
 * thrown.
 *
 * @param string The string which contains the unknown entity
 * @param entity The name of the entity that is unknown
 * @return A substitution for the entity or nil
 */
-	   (OFString*)string: (OFString*)string
  containsUnknownEntityNamed: (OFString*)entity;
@end

/*!
 * @brief A category for unescaping XML in strings.
 */
@interface OFString (XMLUnescaping)

Modified src/OFString.h from [ec74b3531b] to [f401ec63ba].

71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
#endif

@class OFArray;
@class OFURL;

/*!
 * @brief A class for handling strings.
 *
 * <b>Warning:</b> If you add methods to OFString using a category, you are not
 * allowed to access the ivars directly, as these might be still uninitialized
 * for a constant string and get initialized on the first message! Therefore,
 * you should use the corresponding methods to get the ivars, which ensures the
 * constant string is initialized.
 */
@interface OFString: OFObject <OFCopying, OFMutableCopying, OFComparing,
    OFSerialization, OFJSONRepresentation>
#ifdef OF_HAVE_PROPERTIES
@property (readonly) size_t length;
#endif








<
<
<
<
<
<







71
72
73
74
75
76
77






78
79
80
81
82
83
84
#endif

@class OFArray;
@class OFURL;

/*!
 * @brief A class for handling strings.






 */
@interface OFString: OFObject <OFCopying, OFMutableCopying, OFComparing,
    OFSerialization, OFJSONRepresentation>
#ifdef OF_HAVE_PROPERTIES
@property (readonly) size_t length;
#endif

624
625
626
627
628
629
630
631

632
633
634
635
636
637
638
639
640
641
642
643

644
645
646
647
648
649
650
- (of_range_t)rangeOfString: (OFString*)string;

/*!
 * @brief Returns the range of the string.
 *
 * @param string The string to search
 * @param options Options modifying search behaviour.
 *		  Possible values: OF_STRING_SEARCH_BACKWARDS

 * @return The range of the first occurrence of the string or a range with
 *	   OF_NOT_FOUND as start position if it was not found
 */
- (of_range_t)rangeOfString: (OFString*)string
		    options: (int)options;

/*!
 * @brief Returns the range of the string in the specified range.
 *
 * @param string The string to search
 * @param options Options modifying search behaviour.
 *		  Possible values: OF_STRING_SEARCH_BACKWARDS

 * @param range The range in which to search
 * @return The range of the first occurrence of the string or a range with
 *	   OF_NOT_FOUND as start position if it was not found
 */
- (of_range_t)rangeOfString: (OFString*)string
		    options: (int)options
		      range: (of_range_t)range;







|
>











|
>







618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
- (of_range_t)rangeOfString: (OFString*)string;

/*!
 * @brief Returns the range of the string.
 *
 * @param string The string to search
 * @param options Options modifying search behaviour.
 *		  Possible values:
 *		    * OF_STRING_SEARCH_BACKWARDS
 * @return The range of the first occurrence of the string or a range with
 *	   OF_NOT_FOUND as start position if it was not found
 */
- (of_range_t)rangeOfString: (OFString*)string
		    options: (int)options;

/*!
 * @brief Returns the range of the string in the specified range.
 *
 * @param string The string to search
 * @param options Options modifying search behaviour.
 *		  Possible values:
 *		    * OF_STRING_SEARCH_BACKWARDS
 * @param range The range in which to search
 * @return The range of the first occurrence of the string or a range with
 *	   OF_NOT_FOUND as start position if it was not found
 */
- (of_range_t)rangeOfString: (OFString*)string
		    options: (int)options
		      range: (of_range_t)range;
703
704
705
706
707
708
709
710

711
712
713
714
715
716
717
/*!
 * @brief Creates a new string by replacing the occurrences of the specified
 *	  string in the specified range with the specified replacement.
 *
 * @param string The string to replace
 * @param replacement The string with which it should be replaced
 * @param options Options modifying search behaviour.
 *		  Possible values: None yet

 * @param range The range in which to replace the string
 * @return A new string with the occurrences of the specified string replaced
 */
- (OFString*)stringByReplacingOccurrencesOfString: (OFString*)string
				       withString: (OFString*)replacement
					  options: (int)options
					    range: (of_range_t)range;







|
>







699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
/*!
 * @brief Creates a new string by replacing the occurrences of the specified
 *	  string in the specified range with the specified replacement.
 *
 * @param string The string to replace
 * @param replacement The string with which it should be replaced
 * @param options Options modifying search behaviour.
 *		  Possible values:
 *		    * None yet
 * @param range The range in which to replace the string
 * @return A new string with the occurrences of the specified string replaced
 */
- (OFString*)stringByReplacingOccurrencesOfString: (OFString*)string
				       withString: (OFString*)replacement
					  options: (int)options
					    range: (of_range_t)range;
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
 * @return The string in lowercase
 */
- (OFString*)lowercaseString;

/*!
 * @brief Returns the string capitalized.
 *
 * @note This only considers spaces, tab and newlines to be word delimiters!
 *	 Also note that this might change in the future to all word delimiters
 *	 specified by Unicode!
 *
 * @return The capitalized string
 */
- (OFString*)capitalizedString;








|







726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
 * @return The string in lowercase
 */
- (OFString*)lowercaseString;

/*!
 * @brief Returns the string capitalized.
 *
 * @note This only considers spaces, tabs and newlines to be word delimiters!
 *	 Also note that this might change in the future to all word delimiters
 *	 specified by Unicode!
 *
 * @return The capitalized string
 */
- (OFString*)capitalizedString;

787
788
789
790
791
792
793
794
795

796
797
798
799
800
801
802
 */
- (OFArray*)componentsSeparatedByString: (OFString*)delimiter;

/*!
 * @brief Separates an OFString into an OFArray of OFStrings.
 *
 * @param delimiter The delimiter for separating
 * @param options Options according to which the string should be separated
 * 		  Possible values: OF_STRING_SKIP_EMPTY

 * @return An autoreleased OFArray with the separated string
 */
- (OFArray*)componentsSeparatedByString: (OFString*)delimiter
				options: (int)options;

/*!
 * @brief Returns the components of the path.







|
|
>







784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
 */
- (OFArray*)componentsSeparatedByString: (OFString*)delimiter;

/*!
 * @brief Separates an OFString into an OFArray of OFStrings.
 *
 * @param delimiter The delimiter for separating
 * @param options Options according to which the string should be separated.
 * 		  Possible values:
 * 		    * OF_STRING_SKIP_EMPTY
 * @return An autoreleased OFArray with the separated string
 */
- (OFArray*)componentsSeparatedByString: (OFString*)delimiter
				options: (int)options;

/*!
 * @brief Returns the components of the path.

Modified src/OFThreadPool.h from [1c5160c994] to [f7a65bf244].

60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
 *	    determined, the pool will only have one thread!
 *
 * @param size The number of threads for the pool
 * @return A new thread pool with the specified number of threads
 */
+ (instancetype)threadPoolWithSize: (size_t)size;

/*!
 * @brief Initializes an already allocated OFThreadPool with one thread for
 *	  each core in the system.
 *
 * @warning If for some reason the number of cores in the system could not be
 *	    determined, the pool will only have one thread!
 *
 * @return An initialized OFThreadPool with one thread for each core in the
 *	   system
 */
- init;

/*!
 * @brief Initializes an already allocated OFThreadPool with the specified
 *	  number of threads.
 *
 * @warning If for some reason the number of cores in the system could not be
 *	    determined, the pool will only have one thread!
 *







<
<
<
<
<
<
<
<
<
<
<
<







60
61
62
63
64
65
66












67
68
69
70
71
72
73
 *	    determined, the pool will only have one thread!
 *
 * @param size The number of threads for the pool
 * @return A new thread pool with the specified number of threads
 */
+ (instancetype)threadPoolWithSize: (size_t)size;













/*!
 * @brief Initializes an already allocated OFThreadPool with the specified
 *	  number of threads.
 *
 * @warning If for some reason the number of cores in the system could not be
 *	    determined, the pool will only have one thread!
 *