Index: src/OFArray.h ================================================================== --- src/OFArray.h +++ src/OFArray.h @@ -27,22 +27,56 @@ #import "OFCollection.h" #import "OFEnumerator.h" #import "OFSerialization.h" #import "OFJSONRepresentation.h" #import "OFBinaryPackRepresentation.h" + +/*! @file */ @class OFString; enum { OF_SORT_OPTIONS_DESCENDING = 1 }; #ifdef OF_HAVE_BLOCKS +/*! + * @brief A block for enumerating an OFArray. + * + * @param object The current object + * @param index The index of the current object + * @param stop A pointer to a variable that can be set to true to stop the + * enumeration + */ typedef void (^of_array_enumeration_block_t)(id object, size_t index, bool *stop); -typedef bool (^of_array_filter_block_t)(id odject, size_t index); + +/*! + * @brief A block for filtering an OFArray. + * + * @param object The object to inspect + * @param index The index of the object to inspect + * @return Whether the object should be in the filtered array + */ +typedef bool (^of_array_filter_block_t)(id object, size_t index); + +/*! + * @brief A block for mapping objects to objects in an OFArray. + * + * @param object The object to map + * @param index The index of the object to map + * @return The object to map to + */ typedef id (^of_array_map_block_t)(id object, size_t index); + +/*! + * @brief A block for folding an OFArray. + * + * @param left The object to which the object has been folded so far + * @param right The object that should be added to the left object + * @return The left and right side folded into one object + */ typedef id (^of_array_fold_block_t)(id left, id right); #endif /*! * @brief An abstract class for storing objects in an array. Index: src/OFCountedSet.h ================================================================== --- src/OFCountedSet.h +++ src/OFCountedSet.h @@ -13,12 +13,22 @@ * LICENSE.GPLv2 or LICENSE.GPLv3 respectively included in the packaging of this * file. */ #import "OFSet.h" + +/*! @file */ #ifdef OF_HAVE_BLOCKS +/*! + * @brief A block for enumerating an OFCountedSet. + * + * @param object The current object + * @param count The count of the object + * @param stop A pointer to a variable that can be set to true to stop the + * enumeration + */ typedef void (^of_counted_set_enumeration_block_t)(id object, size_t count, bool *stop); #endif /*! Index: src/OFHTTPServer.h ================================================================== --- src/OFHTTPServer.h +++ src/OFHTTPServer.h @@ -44,11 +44,11 @@ /*! * @brief This method is called when the HTTP server's listening socket * encountered an exception. * * @param server The HTTP server which encountered an exception - * @param exception The exception that occurred on the HTTP server's listening + * @param exception The exception which occurred on the HTTP server's listening * socket * @return Whether to continue listening. If you return false, existing * connections will still be handled and you can start accepting new * connections again by calling @ref OFHTTPServer::start again. */ Index: src/OFMapTable.h ================================================================== --- src/OFMapTable.h +++ src/OFMapTable.h @@ -15,10 +15,12 @@ */ #import "OFObject.h" #import "OFEnumerator.h" +/*! @file */ + /** * @brief A struct describing the functions to be used by the map table. */ typedef struct of_map_table_functions_t { /// The function to retain keys / values @@ -30,14 +32,29 @@ /// The function to compare keys / values bool (*equal)(void *value1, void *value2); } of_map_table_functions_t; #ifdef OF_HAVE_BLOCKS +/*! + * @brief A block for enumerating an OFMapTable. + * + * @param key The current key + * @param value The current value + * @param stop A pointer to a variable that can be set to true to stop the + * enumeration + */ typedef void (^of_map_table_enumeration_block_t)(void *key, void *value, bool *stop); -typedef void* (^of_map_table_replace_block_t)(void *key, void *value, - bool *stop); + +/*! + * @brief A block for replacing values in an OFMapTable. + * + * @param key The key of the value to replace + * @param value The value to replace + * @return The value to replace the value with + */ +typedef void* (^of_map_table_replace_block_t)(void *key, void *value); #endif @class OFMapTableEnumerator; /** Index: src/OFMapTable.m ================================================================== --- src/OFMapTable.m +++ src/OFMapTable.m @@ -597,32 +597,32 @@ } - (void)replaceValuesUsingBlock: (of_map_table_replace_block_t)block { size_t i; - bool stop = false; unsigned long mutations = _mutations; - for (i = 0; i < _capacity && !stop; i++) { + for (i = 0; i < _capacity; i++) { if (_mutations != mutations) @throw [OFEnumerationMutationException exceptionWithClass: [self class] object: self]; if (_buckets[i] != NULL && _buckets[i] != &deleted) { - void *old, *new; + void *new; - new = block(_buckets[i]->key, _buckets[i]->value, - &stop); + new = block(_buckets[i]->key, _buckets[i]->value); if (new == NULL) @throw [OFInvalidArgumentException exceptionWithClass: [self class] selector: _cmd]; - old = _buckets[i]->value; - _buckets[i]->value = _valueFunctions.retain(new); - _valueFunctions.release(old); + if (new != _buckets[i]->value) { + _valueFunctions.release(_buckets[i]->value); + _buckets[i]->value = + _valueFunctions.retain(new); + } } } } #endif Index: src/OFMutableArray.h ================================================================== --- src/OFMutableArray.h +++ src/OFMutableArray.h @@ -13,13 +13,22 @@ * LICENSE.GPLv2 or LICENSE.GPLv3 respectively included in the packaging of this * file. */ #import "OFArray.h" + +/*! @file */ #ifdef OF_HAVE_BLOCKS -typedef id (^of_array_replace_block_t)(id obj, size_t idx, bool *stop); +/*! + * @brief A block for replacing values in an OFMutableArray. + * + * @param object The object to replace + * @param index The index of the object to replace + * @return The object to replace the object with + */ +typedef id (^of_array_replace_block_t)(id object, size_t index); #endif /*! * @brief An abstract class for storing, adding and removing objects in an * array. Index: src/OFMutableArray.m ================================================================== --- src/OFMutableArray.m +++ src/OFMutableArray.m @@ -374,12 +374,15 @@ #ifdef OF_HAVE_BLOCKS - (void)replaceObjectsUsingBlock: (of_array_replace_block_t)block { [self enumerateObjectsUsingBlock: ^ (id object, size_t index, bool *stop) { - [self replaceObjectAtIndex: index - withObject: block(object, index, stop)]; + id new = block(object, index); + + if (new != object) + [self replaceObjectAtIndex: index + withObject: new]; }]; } #endif - (void)exchangeObjectAtIndex: (size_t)index1 Index: src/OFMutableArray_adjacent.m ================================================================== --- src/OFMutableArray_adjacent.m +++ src/OFMutableArray_adjacent.m @@ -350,35 +350,35 @@ - (void)replaceObjectsUsingBlock: (of_array_replace_block_t)block { id *objects = [_array items]; size_t i, count = [_array count]; - bool stop = false; unsigned long mutations = _mutations; - for (i = 0; i < count && !stop; i++) { - id newObject; + for (i = 0; i < count; i++) { + id new; if (_mutations != mutations) @throw [OFEnumerationMutationException exceptionWithClass: [self class] object: self]; - newObject = block(objects[i], i, &stop); + new = block(objects[i], i); - if (newObject == nil) + if (new == nil) @throw [OFInvalidArgumentException exceptionWithClass: [self class] selector: _cmd]; - [newObject retain]; - [objects[i] release]; - objects[i] = newObject; + if (new != objects[i]) { + [objects[i] release]; + objects[i] = [new retain]; + } } } #endif - (void)makeImmutable { object_setClass(self, [OFArray_adjacent class]); } @end Index: src/OFMutableDictionary.h ================================================================== --- src/OFMutableDictionary.h +++ src/OFMutableDictionary.h @@ -13,13 +13,22 @@ * LICENSE.GPLv2 or LICENSE.GPLv3 respectively included in the packaging of this * file. */ #import "OFDictionary.h" + +/*! @file */ #ifdef OF_HAVE_BLOCKS -typedef id (^of_dictionary_replace_block_t)(id key, id object, bool *stop); +/*! + * @brief A block for replacing objects in an OFMutableDictionary. + * + * @param key The key of the object to replace + * @param object The object to replace + * @return The object to replace the object with + */ +typedef id (^of_dictionary_replace_block_t)(id key, id object); #endif /*! * @brief An abstract class for storing and changing objects in a dictionary. */ Index: src/OFMutableDictionary.m ================================================================== --- src/OFMutableDictionary.m +++ src/OFMutableDictionary.m @@ -198,15 +198,19 @@ #ifdef OF_HAVE_BLOCKS - (void)replaceObjectsUsingBlock: (of_dictionary_replace_block_t)block { [self enumerateKeysAndObjectsUsingBlock: ^ (id key, id object, bool *stop) { - [self setObject: block(key, object, stop) - forKey: key]; + id new = block(key, object); + + if (new != object) { + [self setObject: block(key, object) + forKey: key]; + } }]; } #endif - (void)makeImmutable { } @end Index: src/OFMutableDictionary_hashtable.m ================================================================== --- src/OFMutableDictionary_hashtable.m +++ src/OFMutableDictionary_hashtable.m @@ -62,12 +62,12 @@ #ifdef OF_HAVE_BLOCKS - (void)replaceObjectsUsingBlock: (of_dictionary_replace_block_t)block { @try { [_mapTable replaceValuesUsingBlock: - ^ void* (void *key, void *value, bool *stop) { - return block(key, value, stop); + ^ void* (void *key, void *value) { + return block(key, value); }]; } @catch (OFEnumerationMutationException *e) { @throw [OFEnumerationMutationException exceptionWithClass: [self class] object: self]; Index: src/OFSet.h ================================================================== --- src/OFSet.h +++ src/OFSet.h @@ -24,15 +24,31 @@ #include #import "OFObject.h" #import "OFCollection.h" #import "OFSerialization.h" + +/*! @file */ @class OFArray; #ifdef OF_HAVE_BLOCKS +/*! + * @brief A block for enumerating an OFSet. + * + * @param object The current object + * @param stop A pointer to a variable that can be set to true to stop the + * enumeration + */ typedef void (^of_set_enumeration_block_t)(id object, bool *stop); + +/*! + * @brief A block for filtering an OFSet. + * + * @param object The object to inspect + * @return Whether the object should be in the filtered set + */ typedef bool (^of_set_filter_block_t)(id object); #endif /*! * @brief An abstract class for an unordered set of unique objects. Index: src/OFStream.h ================================================================== --- src/OFStream.h +++ src/OFStream.h @@ -23,20 +23,40 @@ #include #import "OFObject.h" #import "OFString.h" + +/*! @file */ @class OFStream; @class OFDataArray; @class OFException; #ifdef OF_HAVE_BLOCKS -typedef bool (^of_stream_async_read_block_t)(OFStream*, void*, size_t, - OFException*); -typedef bool (^of_stream_async_read_line_block_t)(OFStream*, OFString*, - OFException*); +/*! + * @brief A block which is called when data was read from the stream. + * + * @param stream The stream on which data was read + * @param buffer A buffer with the data that has been read + * @param length The length of the data that has been read + * @param exception An exception which occurred while reading or nil on success + * @return A bool whether the same block should be used for the next read + */ +typedef bool (^of_stream_async_read_block_t)(OFStream *stream, void *buffer, + size_t length, OFException *exception); + +/*! + * @brief A block which is called when a line was read from the stream. + * + * @param stream The stream on which a line was read + * @param line The line which has been read + * @param exception An exception which occurred while reading or nil on success + * @return A bool whether the same block should be used for the next read + */ +typedef bool (^of_stream_async_read_line_block_t)(OFStream *stream, + OFString *line, OFException *exception); #endif /*! * @brief A base class for different types of streams. * Index: src/OFString+XMLUnescaping.h ================================================================== --- src/OFString+XMLUnescaping.h +++ src/OFString+XMLUnescaping.h @@ -13,10 +13,12 @@ * LICENSE.GPLv2 or LICENSE.GPLv3 respectively included in the packaging of this * file. */ #import "OFString.h" + +/*! @file */ #ifdef __cplusplus extern "C" { #endif extern int _OFString_XMLUnescaping_reference; @@ -23,10 +25,18 @@ #ifdef __cplusplus } #endif #ifdef OF_HAVE_BLOCKS +/*! + * @brief A block which is called to replace unknown XML entities in an XML + * string. + * + * @param string The XML string which contains an unknown entity + * @param entity The XML entity which is unknown + * @return A replacement string for the unknown entity + */ typedef OFString* (^of_string_xml_unescaping_block_t)(OFString *string, OFString *entity); #endif /*! Index: src/OFString.h ================================================================== --- src/OFString.h +++ src/OFString.h @@ -26,10 +26,12 @@ #import "OFObject.h" #import "OFSerialization.h" #import "OFJSONRepresentation.h" #import "OFBinaryPackRepresentation.h" + +/*! @file */ @class OFConstantString; #if defined(__cplusplus) && __cplusplus >= 201103L typedef char16_t of_char16_t; @@ -38,12 +40,10 @@ typedef uint_least16_t of_char16_t; typedef uint_least32_t of_char32_t; #endif typedef of_char32_t of_unichar_t; -/*! @file */ - /*! * @brief The encoding of a string. */ typedef enum of_string_encoding_t { /*! UTF-8 */ @@ -67,10 +67,17 @@ /* FIXME */ #define OF_STRING_ENCODING_NATIVE OF_STRING_ENCODING_UTF_8 #ifdef OF_HAVE_BLOCKS +/*! + * @brief A block for enumerating the lines of a string. + * + * @param line The current line + * @param stop A pointer to a variable that can be set to true to stop the + * enumeration + */ typedef void (^of_string_line_enumeration_block_t)(OFString *line, bool *stop); #endif @class OFArray; @class OFURL; Index: src/OFTCPSocket.h ================================================================== --- src/OFTCPSocket.h +++ src/OFTCPSocket.h @@ -30,18 +30,39 @@ #import "OFStreamSocket.h" #ifdef _WIN32 # include #endif + +/*! @file */ @class OFTCPSocket; @class OFString; #ifdef OF_HAVE_BLOCKS -typedef void (^of_tcpsocket_async_connect_block_t)(OFTCPSocket*, OFException*); -typedef bool (^of_tcpsocket_async_accept_block_t)(OFTCPSocket*, OFTCPSocket*, - OFException*); +/*! + * @brief A block which is called when the socket connected. + * + * @param socket The socket which connected + * @param exception An exception which occurred while connecting the socket or + * nil on success + */ +typedef void (^of_tcpsocket_async_connect_block_t)(OFTCPSocket *socket, + OFException *exception); + +/*! + * @brief A block which is called when the socket accepted a connection. + * + * @param socket The socket which accepted the connection + * @param acceptedSocket The socket which has been accepted + * @param exception An exception which occurred while accepting the socket or + * nil on success + * @return A bool whether the same block should be used for the next incoming + * connection + */ +typedef bool (^of_tcpsocket_async_accept_block_t)(OFTCPSocket *socket, + OFTCPSocket *acceptedSocket, OFException *exception); #endif /*! * @brief A class which provides functions to create and use TCP sockets. * Index: src/OFThread.h ================================================================== --- src/OFThread.h +++ src/OFThread.h @@ -21,16 +21,23 @@ /* Haiku used to define this for some unknown reason which causes trouble */ #ifdef protected # undef protected #endif + +/*! @file */ @class OFDate; @class OFSortedList; @class OFRunLoop; #ifdef OF_HAVE_BLOCKS +/*! + * @brief A block to be executed in a new thread. + * + * @return The object which should be returned when the thread is joined + */ typedef id (^of_thread_block_t)(void); #endif /*! * @brief A class which provides portable threads. Index: src/OFThreadPool.h ================================================================== --- src/OFThreadPool.h +++ src/OFThreadPool.h @@ -13,12 +13,17 @@ * LICENSE.GPLv2 or LICENSE.GPLv3 respectively included in the packaging of this * file. */ #import "OFObject.h" + +/*! @file */ #ifdef OF_HAVE_BLOCKS +/*! + * @brief A block for a job which should be executed in a thread pool. + */ typedef void (^of_thread_pool_block_t)(void); #endif @class OFMutableArray; @class OFList; Index: src/OFTimer.h ================================================================== --- src/OFTimer.h +++ src/OFTimer.h @@ -13,20 +13,27 @@ * LICENSE.GPLv2 or LICENSE.GPLv3 respectively included in the packaging of this * file. */ #import "OFObject.h" + +/*! @file */ @class OFTimer; @class OFDate; @class OFRunLoop; #ifdef OF_HAVE_THREADS @class OFCondition; #endif #ifdef OF_HAVE_BLOCKS -typedef void (^of_timer_block_t)(OFTimer*); +/*! + * @brief A block to execute when a timer fires. + * + * @param timer The timer which fired + */ +typedef void (^of_timer_block_t)(OFTimer *timer); #endif /*! * @brief A class for creating and firing timers. */ Index: src/exceptions/OFException.h ================================================================== --- src/exceptions/OFException.h +++ src/exceptions/OFException.h @@ -48,13 +48,13 @@ * @return An initialized OFException */ - initWithClass: (Class)class_; /*! - * @brief Returns the class of the object in which the exception happened. + * @brief Returns the class of the object in which the exception occurred. * - * @return The class of the object in which the exception happened + * @return The class of the object in which the exception occurred */ - (Class)inClass; /*! * @brief Returns a description of the exception. Index: tests/OFArrayTests.m ================================================================== --- tests/OFArrayTests.m +++ tests/OFArrayTests.m @@ -277,12 +277,11 @@ TEST(@"Detection of mutation during enumeration using blocks", ok) } TEST(@"-[replaceObjectsUsingBlock:]", - R([m[0] replaceObjectsUsingBlock: - ^ id (id obj, size_t idx, bool *stop) { + R([m[0] replaceObjectsUsingBlock: ^ id (id obj, size_t idx) { switch (idx) { case 0: return @"foo"; case 1: return @"bar"; Index: tests/OFDictionaryTests.m ================================================================== --- tests/OFDictionaryTests.m +++ tests/OFDictionaryTests.m @@ -161,12 +161,11 @@ [dict removeObjectForKey: @""]; } TEST(@"-[replaceObjectsUsingBlock:]", - R([dict replaceObjectsUsingBlock: - ^ id (id key, id obj, bool *stop) { + R([dict replaceObjectsUsingBlock: ^ id (id key, id obj) { if ([key isEqual: keys[0]]) return @"value_1"; if ([key isEqual: keys[1]]) return @"value_2";