ObjFW  Check-in [650b4be224]

 *
 * @param object An object
 * @return A new autoreleased OFArray
 */
+ (instancetype)arrayWithObject: (ObjectType)object;

/*!
 * @brief Creates a new OFArray with the specified objects, terminated by nil.
 * @brief Creates a new OFArray with the specified objects, terminated by `nil`.
 *
 * @param firstObject The first object in the array
 * @return A new autoreleased OFArray
 */
+ (instancetype)arrayWithObjects: (ObjectType)firstObject, ... OF_SENTINEL;

/*!

 * @param object The object which is checked for being in the array
 * @return A boolean whether the array contains an object with the specified
 *	   address
 */
- (bool)containsObjectIdenticalTo: (nullable ObjectType)object;

/*!
 * @brief Returns the first object of the array or nil.
 * @brief Returns the first object of the array or `nil`.
 *
 * @warning The returned object is *not* retained and autoreleased for
 *	    performance reasons!
 *
 * @return The first object of the array or nil
 * @return The first object of the array or `nil`
 */
- (nullable ObjectType)firstObject;

/*!
 * @brief Returns the last object of the array or nil.
 * @brief Returns the last object of the array or `nil`.
 *
 * @warning The returned object is *not* retained and autoreleased for
 *	    performance reasons!
 *
 * @return The last object of the array or nil
 * @return The last object of the array or `nil`
 */
- (nullable ObjectType)lastObject;

/*!
 * @brief Returns the objects in the specified range as a new OFArray.
 *
 * @param range The range for the subarray

 */
- (OFArray OF_GENERIC(ObjectType)*)filteredArrayUsingBlock:
    (of_array_filter_block_t)block;

/*!
 * @brief Folds the array to a single object using the specified block.
 *
 * If the array is empty, it will return nil.
 * If the array is empty, it will return `nil`.
 *
 * If there is only one object in the array, that object will be returned and
 * the block will not be invoked.
 *
 * If there are at least two objects, the block is invoked for each object
 * except the first, where left is always to what the array has already been
 * folded and right what should be added to left.

 * @return A new, autoreleased OFString
 */
- (OFString*)localDateStringWithFormat: (OFConstantString*)format;

/*!
 * @brief Returns the earlier of the two dates.
 *
 * If the argument is nil, it returns the receiver.
 * If the argument is `nil`, it returns the receiver.
 *
 * @param otherDate Another date
 * @return The earlier date of the two dates
 */
- (OFDate*)earlierDate: (OFDate*)otherDate;

/*!
 * @brief Returns the later of the two dates.
 *
 * If the argument is nil, it returns the receiver.
 * If the argument is `nil`, it returns the receiver.
 *
 * @param otherDate Another date
 * @return The later date of the two dates
 */
- (OFDate*)laterDate: (OFDate*)otherDate;

/*!

 * @param arguments A va_list of the other arguments
 * @return An initialized OFDictionary
 */
- initWithKey: (KeyType)firstKey
    arguments: (va_list)arguments;

/*!
 * @brief Returns the object for the given key or nil if the key was not found.
 * @brief Returns the object for the given key or `nil` if the key was not
 *	  found.
 *
 * @warning The returned object is *not* retained and autoreleased for
 *	    performance reasons!
 *
 * @param key The key whose object should be returned
 * @return The object for the given key or nil if the key was not found
 * @return The object for the given key or `nil` if the key was not found
 */
- (nullable ObjectType)objectForKey: (KeyType)key;
- (nullable ObjectType)objectForKeyedSubscript: (KeyType)key;

/*!
 * @brief Checks whether the dictionary contains an object equal to the
 *	  specified object.

#else
# ifndef DOXYGEN
#  define ObjectType id
# endif
@interface OFEnumerator: OFObject
#endif
/*!
 * @brief Returns the next object or nil if there is none left.
 * @brief Returns the next object or `nil` if there is none left.
 *
 * @return The next object or nil if there is none left
 * @return The next object or `nil` if there is none left
 */
- (nullable ObjectType)nextObject;

/*!
 * @brief Returns an array of all remaining objects in the collection.
 *
 * @return An array of all remaining objects in the collection

 * @brief Returns the name of the INI category.
 *
 * @return The name of the INI category
 */
- (OFString*)name;

/*!
 * @brief Returns the string value for the specified key, or nil if it does not
 *	  exist.
 * @brief Returns the string value for the specified key, or `nil` if it does
 *	  not exist.
 *
 * If the specified key is a multi-key (see @ref arrayForKey:), the value of
 * the first key/value pair found is returned.
 *
 * @param key The key for which the string value should be returned
 * @return The string value for the specified key, or nil if it does not exist
 * @return The string value for the specified key, or `nil` if it does not exist
 */
- (nullable OFString*)stringForKey: (OFString*)key;

/*!
 * @brief Returns the string value for the specified key or the specified
 *	  default value if it does not exist.
 *

 * @brief Returns an OFEnumerator to enumerate through all objects of the list.
 *
 * @returns An OFEnumerator to enumerate through all objects of the list
 */
- (OFEnumerator OF_GENERIC(ObjectType)*)objectEnumerator;

/*!
 * @brief Returns the first object of the list or nil.
 * @brief Returns the first object of the list or `nil`.
 *
 * @warning The returned object is *not* retained and autoreleased for
 *	    performance reasons!
 *
 * @return The first object of the list or nil
 * @return The first object of the list or `nil`
 */
- (nullable ObjectType)firstObject;

/*!
 * @brief Returns the last object of the list or nil.
 * @brief Returns the last object of the list or `nil`.
 *
 * @warning The returned object is *not* retained and autoreleased for
 *	    performance reasons!
 *
 * @return The last object of the list or nil
 * @return The last object of the list or `nil`
 */
- (nullable ObjectType)lastObject;

/*!
 * @brief Removes all objects from the list.
 */
- (void)removeAllObjects;

 */
+ (void)initialize;

/*!
 * @brief Allocates memory for an instance of the class and sets up the memory
 *	  pool for the object.
 *
 * This method will never return nil, instead, it will throw an
 * OFAllocFailedException.
 * This method will never return `nil`, instead, it will throw an
 * @ref OFAllocFailedException.
 *
 * @return The allocated object
 */
+ alloc;

/*!
 * @brief Allocates memory for a new instance and calls @ref init on it.

/*!
 * @brief Returns the implementation of the instance method for the specified
 *	  selector.
 *
 * @param selector The selector for which the method should be returned
 * @return The implementation of the instance method for the specified selector
 *	   or nil if it isn't implemented
 *	   or `nil` if it isn't implemented
 */
+ (nullable IMP)instanceMethodForSelector: (SEL)selector;

/*!
 * @brief Returns the type encoding of the instance method for the specified
 *	  selector.
 *

 * If the method already exists, it is replaced and the old implementation
 * returned. If the method does not exist, it is added with the specified type
 * encoding.
 *
 * @param selector The selector for the new method
 * @param implementation The implementation for the new method
 * @param typeEncoding The type encoding for the new method
 * @return The old implementation or nil if the method was added
 * @return The old implementation or `nil` if the method was added
 */
+ (nullable IMP)replaceClassMethod: (SEL)selector
		withImplementation: (IMP)implementation
		      typeEncoding: (const char*)typeEncoding;

/*!
 * @brief Replaces or adds an instance method.
 *
 * If the method already exists, it is replaced and the old implementation
 * returned. If the method does not exist, it is added with the specified type
 * encoding.
 *
 * @param selector The selector for the new method
 * @param implementation The implementation for the new method
 * @param typeEncoding The type encoding for the new method
 * @return The old implementation or nil if the method was added
 * @return The old implementation or `nil` if the method was added
 */
+ (nullable IMP)replaceInstanceMethod: (SEL)selector
		   withImplementation: (IMP)implementation
			 typeEncoding: (const char*)typeEncoding;

/*!
 * @brief Adds all methods from the specified class to the class that is the

/*!
 * @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.
 * before they do any initialization themselves. @ref init may never return
 * `nil`, instead an exception (for example @ref
 * OFInitializationFailedException) should be thrown.
 *
 * @return An initialized object
 */
- init;

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

#endif

/*!
 * @brief This method is called when @ref resolveClassMethod: or
 *	  @ref resolveInstanceMethod: returned false. It should return a target
 *	  to which the message should be forwarded.
 *
 * @note When the message should not be forwarded, you should not return nil,
 *	 but instead return the result of the superclass!
 * @note When the message should not be forwarded, you should not return `nil`,
 *	 but instead return the result of `[super
 *	 forwardingTargetForSelector: selector]`.
 *
 * @return The target to forward the message to
 */
- (nullable id)forwardingTargetForSelector: (SEL)selector;

/*!
 * @brief Handles messages which are not understood by the receiver.

/*!
 * @struct of_options_parser_option_t OFOptionsParser.h ObjFW/OFOptionsParser.h
 *
 * @brief An option which can be parsed by an @ref OFOptionsParser.
 */
typedef struct of_options_parser_option_t {
	/*! The short version (e.g. `-v`) of the option or `'\0'` for none */
	/*! The short version (e.g. `-v`) of the option or `\0` for none. */
	of_unichar_t shortOption;

	/*!
	 * The long version (e.g. `--verbose`) of the option or `nil` for none
	 * The long version (e.g. `--verbose`) of the option or `nil` for none.
	 */
	OFString *_Nullable longOption;

	/*!
	 * Whether the option takes an argument
	 * Whether the option takes an argument.
	 *
	 * 0 means it takes no argument.@n
	 * 1 means it takes a required argument.@n
	 * -1 means it takes an optional argument.@n
	 *
	 * All other values are invalid and will throw an
	 * @ref OFInvalidArgumentException.
	 */
	signed char hasArgument;

	/*!
	 * An optional pointer to a bool that is set to whether the option has
	 * been specified
	 * been specified.
	 */
	bool *_Nullable isSpecifiedPtr;

	/*!
	 * An optional pointer to an @ref OFString* that is set to the argument
	 * specified for the option or `nil` for no argument
	 * specified for the option or `nil` for no argument.
	 */
	OFString *__autoreleasing _Nullable *_Nullable argumentPtr;
} of_options_parser_option_t;

/*!
 * @class OFOptionsParser OFOptionsParser.h ObjFW/OFOptionsParser.h
 *

#endif

/*!
 * @brief Creates a new OFOptionsParser which accepts the specified options.
 *
 * @param options An array of @ref of_options_parser_option_t specifying all
 *		  accepted options, terminated with an option whose short
 *		  option is `'\0'` and long option is `nil`.
 *		  option is `\0` and long option is `nil`.
 *
 * @return A new, autoreleased OFOptionsParser
 */
+ (instancetype)parserWithOptions: (const of_options_parser_option_t*)options;

/*!
 * @brief Initializes an already allocated OFOptionsParser so that it accepts
 *	  the specified options.
 *
 * @param options An array of @ref of_options_parser_option_t specifying all
 *		  accepted options, terminated with an option whose short
 *		  option is `'\0'` and long option is `nil`.
 *		  option is `\0` and long option is `nil`.
 *
 * @return An initialized OFOptionsParser
 */
- initWithOptions: (const of_options_parser_option_t*)options;

/*!
 * @brief Returns the next option.
 *
 * If the option is only available as a long option, '-' is returned.
 * If the option is only available as a long option, `-` is returned.
 * Otherwise, the short option is returned, even if it was specified as a long
 * option.@n
 * If an unknown option is specified, '?' is returned.@n
 * If the argument for the option is missing, ':' is returned.@n
 * If there is an argument for the option even though it takes none, '=' is
 * If an unknown option is specified, `?` is returned.@n
 * If the argument for the option is missing, `:` is returned.@n
 * If there is an argument for the option even though it takes none, `=` is
 * returned.@n
 * If all options have been parsed, `'\0'` is returned.
 * If all options have been parsed, `\0` is returned.
 *
 * @note You need to call @ref nextOption repeatedly until it returns `'\0'` to
 * @note You need to call @ref nextOption repeatedly until it returns `\0` to
 *	 make sure all options have been parsed, even if you only rely on the
 *	 optional pointers specified and don't do any parsing yourself.
 *
 * @return The next option
 */
- (of_unichar_t)nextOption;

/*!
 * @brief Returns the last parsed option.
 *
 * If @ref nextOption returned '?' or ':', this returns the option which was
 * If @ref nextOption returned `?` or `:`, this returns the option which was
 * unknown or for which the argument was missing.@n
 * If this returns '-', the last option is only available as a long option (see
 * If this returns `-`, the last option is only available as a long option (see
 * @ref lastLongOption).
 *
 * @return The last parsed option
 */
- (of_unichar_t)lastOption;

/*!
 * @brief Returns the long option for the last parsed option, or `nil` if the
 *	  last parsed option was not passed as a long option by the user.
 *
 * In case @ref nextOption returned '?', this contains the unknown long
 * In case @ref nextOption returned `?`, this contains the unknown long
 * option.@n
 * In case it returned ':', this contains the long option which is missing an
 * In case it returned `:`, this contains the long option which is missing an
 * argument.@n
 * In case it returned '=', this contains the long option for which an argument
 * was specified even though the option takes no argument.
 * In case it returned `=`, this contains the long option for which an
 * argument was specified even though the option takes no argument.
 *
 * @warning Unlike @ref lastOption, which returns the short option even if the
 *	    user specified a long option, this only returns the long option if
 *	    it was actually specified as a long option by the user.
 * @warning Unlike lastOption, which returns the short option even if the user
 *	    specified a long option, this only returns the long option if it
 *	    was actually specified as a long option by the user.
 *
 * @return The last parsed long option or `nil`
 */
- (nullable OFString*)lastLongOption;

/*!
 * @brief Returns the argument for the last parsed option, or `nil` if the last

		of_options_parser_option_t *iter2;
		const of_map_table_functions_t keyFunctions = {
			.hash = stringHash,
			.equal = stringEqual
		};
		const of_map_table_functions_t valueFunctions = { NULL };

		/* Count, sanity check and initialize pointers */
		/* Count, sanity check, initialize pointers */
		for (iter = options;
		    iter->shortOption != '\0' || iter->longOption != nil;
		    iter++) {
			if (iter->hasArgument < -1 || iter->hasArgument > 1)
				@throw [OFInvalidArgumentException exception];

			if (iter->shortOption != '\0' &&

/*!
 * @brief Creates a new OFProcess with the specified program and arguments and
 *	  invokes the program.
 *
 * @param program The program to execute. If it does not start with a slash, the
 *		  search path specified in PATH is used.
 * @param arguments The arguments to pass to the program, or nil
 * @param arguments The arguments to pass to the program, or `nil`
 * @return A new, autoreleased OFProcess.
 */
+ (instancetype)
    processWithProgram: (OFString*)program
	     arguments: (nullable OFArray OF_GENERIC(OFString*)*)arguments;

/*!
 * @brief Creates a new OFProcess with the specified program, program name and
 *	  arguments and invokes the program.
 *
 * @param program The program to execute. If it does not start with a slash, the
 *		  search path specified in PATH is used.
 * @param programName The program name for the program to invoke (argv[0]).
 *		      Usually, this is equal to program.
 * @param arguments The arguments to pass to the program, or nil
 * @param arguments The arguments to pass to the program, or `nil`
 * @return A new, autoreleased OFProcess.
 */
+ (instancetype)
    processWithProgram: (OFString*)program
	   programName: (OFString*)programName
	     arguments: (nullable OFArray OF_GENERIC(OFString*)*)arguments;

/*!
 * @brief Creates a new OFProcess with the specified program, program name,
 *	  arguments and environment and invokes the program.
 *
 * @param program The program to execute. If it does not start with a slash, the
 *		  search path specified in PATH is used.
 * @param programName The program name for the program to invoke (argv[0]).
 *		      Usually, this is equal to program.
 * @param arguments The arguments to pass to the program, or nil
 * @param environment The environment to pass to the program, or nil. If it is
 *		      non-nil, the passed dictionary will be used to override
 *		      the environment. If you want to add to the existing
 *		      environment, you need to get the existing environment
 *		      first, copy it, modify it and then pass it.
 * @param arguments The arguments to pass to the program, or `nil`
 * @param environment The environment to pass to the program, or `nil`. If it
 *		      is not `nil`, the passed dictionary will be used to
 *		      override the environment. If you want to add to the
 *		      existing environment, you need to get the existing
 *		      environment first, copy it, modify it and then pass it.
 * @return A new, autoreleased OFProcess.
 */
+ (instancetype)
    processWithProgram: (OFString*)program
	   programName: (OFString*)programName
	     arguments: (nullable OFArray OF_GENERIC(OFString*)*)arguments
	   environment: (nullable OFDictionary

/*!
 * @brief Initializes an already allocated OFProcess with the specified program
 *	  and arguments and invokes the program.
 *
 * @param program The program to execute. If it does not start with a slash, the
 *		  search path specified in PATH is used.
 * @param arguments The arguments to pass to the program, or nil
 * @param arguments The arguments to pass to the program, or `nil`
 * @return An initialized OFProcess.
 */
- initWithProgram: (OFString*)program
	arguments: (nullable OFArray OF_GENERIC(OFString*)*)arguments;

/*!
 * @brief Initializes an already allocated OFProcess with the specified program,
 *	  program name and arguments and invokes the program.
 *
 * @param program The program to execute. If it does not start with a slash, the
 *		  search path specified in PATH is used.
 * @param programName The program name for the program to invoke (argv[0]).
 *		      Usually, this is equal to program.
 * @param arguments The arguments to pass to the program, or nil
 * @param arguments The arguments to pass to the program, or `nil`
 * @return An initialized OFProcess.
 */
- initWithProgram: (OFString*)program
      programName: (OFString*)programName
	arguments: (nullable OFArray OF_GENERIC(OFString*)*)arguments;

/*!
 * @brief Initializes an already allocated OFProcess with the specified program,
 *	  program name, arguments and environment and invokes the program.
 *
 * @param program The program to execute. If it does not start with a slash, the
 *		  search path specified in PATH is used.
 * @param programName The program name for the program to invoke (argv[0]).
 *		      Usually, this is equal to program.
 * @param arguments The arguments to pass to the program, or nil
 * @param environment The environment to pass to the program, or nil. If it is
 *		      non-nil, the passed dictionary will be used to override
 *		      the environment. If you want to add to the existing
 *		      environment, you need to get the existing environment
 *		      first, copy it, modify it and then pass it.
 * @param arguments The arguments to pass to the program, or `nil`
 * @param environment The environment to pass to the program, or `nil`. If it
 *		      is not `nil`, the passed dictionary will be used to
 *		      override the environment. If you want to add to the
 *		      existing environment, you need to get the existing
 *		      environment first, copy it, modify it and then pass it.
 * @return An initialized OFProcess.
 */
- initWithProgram: (OFString*)program
      programName: (OFString*)programName
	arguments: (nullable OFArray OF_GENERIC(OFString*)*)arguments
      environment: (nullable OFDictionary
		       OF_GENERIC(OFString*, OFString*)*)environment;

 * @param array The array of strings to set
 * @param path The path to store the array of strings at
 */
- (void)setArray: (OFArray OF_GENERIC(OFString*)*)array
	 forPath: (OFString*)path;

/*!
 * @brief Returns the string for the specified path, or nil if the path does
 * @brief Returns the string for the specified path, or `nil` if the path does
 *	  not exist.
 *
 * @param path The path for which the string value should be returned
 * @return The string value of the specified path
 */
- (nullable OFString*)stringForPath: (OFString*)path;

#if defined(OF_HAVE_SOCKETS) && defined(OF_HAVE_BLOCKS)
/*!
 * @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
 * @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 *_Nullable 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 or nil when the end of stream
 * @param line The line which has been read or `nil` when the end of stream
 *	       occurred
 * @param exception An exception which occurred while reading or nil on success
 * @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 *_Nullable line, OFException *_Nullable exception);
#endif

/*!

 *	   stream until the end of the stream is reached.
 */
- (OFDataArray*)readDataArrayTillEndOfStream;

/*!
 * @brief Reads a string with the specified length from the stream.
 *
 * If a \\0 appears in the stream, the string will be truncated at the \\0 and
 * If `\0` appears in the stream, the string will be truncated at the `\0` and
 * the rest of the bytes of the string will be lost. This way, reading from the
 * stream will not break because of a \\0 because the specified number of bytes
 * is still being read and only the string gets truncated.
 * stream will not break because of a `\0` because the specified number of
 * bytes is still being read and only the string gets truncated.
 *
 * @warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * @param length The length (in bytes) of the string to read from the stream
 * @return A string with the specified length
 */
- (OFString*)readStringWithLength: (size_t)length;

/*!
 * @brief Reads a string with the specified encoding and length from the stream.
 *
 * If a \\0 appears in the stream, the string will be truncated at the \\0 and
 * the rest of the bytes of the string will be lost. This way, reading from the
 * stream will not break because of a \\0 because the specified number of bytes
 * is still being read and only the string gets truncated.
 * If a `\0` appears in the stream, the string will be truncated at the `\0`
 * and the rest of the bytes of the string will be lost. This way, reading from
 * the stream will not break because of a `\0` because the specified number of
 * bytes is still being read and only the string gets truncated.
 *
 * @warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * @param encoding The encoding of the string to read from the stream
 * @param length The length (in bytes) of the string to read from the stream
 * @return A string with the specified length
 */
- (OFString*)readStringWithLength: (size_t)length
			 encoding: (of_string_encoding_t)encoding;

/*!
 * @brief Reads until a newline, \\0 or end of stream occurs.
 * @brief Reads until a newline, `\0` or end of stream occurs.
 *
 * @return The line that was read, autoreleased, or nil if the end of the
 * @return The line that was read, autoreleased, or `nil` if the end of the
 *	   stream has been reached.
 */
- (nullable OFString*)readLine;

/*!
 * @brief Reads with the specified encoding until a newline, \\0 or end of
 * @brief Reads with the specified encoding until a newline, `\0` or end of
 *	  stream occurs.
 *
 * @param encoding The encoding used by the stream
 * @return The line that was read, autoreleased, or nil if the end of the
 * @return The line that was read, autoreleased, or `nil` if the end of the
 *	   stream has been reached.
 */
- (nullable OFString*)readLineWithEncoding: (of_string_encoding_t)encoding;

#ifdef OF_HAVE_SOCKETS
/*!
 * @brief Asyncronously reads until a newline, \\0, end of stream or an
 * @brief Asyncronously reads until a newline, `\0`, end of stream or an
 *	  exception occurs.
 *
 * @note The stream must implement @ref fileDescriptorForReading and return a
 *	 valid file descriptor in order for this to work!
 *
 * @param target The target on which to call the selector when the data has
 *		 been received. If the method returns true, it will be called
 *		 again when the next line has been received. If you want the
 *		 next method in the queue to handle the next line, you need to
 *		 return false from the method
 * @param selector The selector to call on the target. The signature must be
 *		   `bool (OFStream *stream, OFString *line,
 *		   OFException *exception)`.
 */
- (void)asyncReadLineWithTarget: (id)target
		       selector: (SEL)selector;

/*!
 * @brief Asyncronously reads with the specified encoding until a newline, \\0,
 *	  end of stream or an exception occurs.
 * @brief Asyncronously reads with the specified encoding until a newline,
 *	  `\0`, end of stream or an exception occurs.
 *
 * @note The stream must implement @ref fileDescriptorForReading and return a
 *	 valid file descriptor in order for this to work!
 *
 * @param encoding The encoding used by the stream
 * @param target The target on which to call the selector when the data has
 *		 been received. If the method returns true, it will be called
 *		 again when the next line has been received. If you want the
 *		 next method in the queue to handle the next line, you need to
 *		 return false from the method
 * @param selector The selector to call on the target. The signature must be
 *		   `bool (OFStream *stream, OFString *line,
 *		   OFException *exception)`.
 */
- (void)asyncReadLineWithEncoding: (of_string_encoding_t)encoding
			   target: (id)target
			 selector: (SEL)selector;

# ifdef OF_HAVE_BLOCKS
/*!
 * @brief Asyncronously reads until a newline, \\0, end of stream or an
 * @brief Asyncronously reads until a newline, `\0`, end of stream or an
 *	  exception occurs.
 *
 * @note The stream must implement @ref fileDescriptorForReading and return a
 *	 valid file descriptor in order for this to work!
 *
 * @param block The block to call when the data has been received.
 *		If the block returns true, it will be called again when the next
 *		line has been received. If you want the next block in the queue
 *		to handle the next line, you need to return false from the
 *		block.
 */
- (void)asyncReadLineWithBlock: (of_stream_async_read_line_block_t)block;

/*!
 * @brief Asyncronously reads with the specified encoding until a newline, \\0,
 *	  end of stream or an exception occurs.
 * @brief Asyncronously reads with the specified encoding until a newline,
 *	  `\0`, end of stream or an exception occurs.
 *
 * @note The stream must implement @ref fileDescriptorForReading and return a
 *	 valid file descriptor in order for this to work!
 *
 * @param encoding The encoding used by the stream
 * @param block The block to call when the data has been received.
 *		If the block returns true, it will be called again when the next
 *		line has been received. If you want the next block in the queue
 *		to handle the next line, you need to return false from the
 *		block.
 */
- (void)asyncReadLineWithEncoding: (of_string_encoding_t)encoding
			    block: (of_stream_async_read_line_block_t)block;
# endif
#endif

/*!
 * @brief Tries to read a line from the stream (see readLine) and returns nil if
 *	  no complete line has been received yet.
 * @brief Tries to read a line from the stream (see readLine) and returns `nil`
 *	  if no complete line has been received yet.
 *
 * @return The line that was read, autoreleased, or nil if the line is not
 * @return The line that was read, autoreleased, or `nil` if the line is not
 *	   complete yet
 */
- (nullable 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
 *	  @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
 * @return The line that was read, autoreleased, or `nil` if the line is not
 *	   complete yet
 */
- (nullable OFString*)tryReadLineWithEncoding: (of_string_encoding_t)encoding;

/*!
 * @brief Reads until the specified string or \\0 is found or the end of stream
 *	  occurs.
 * @brief Reads until the specified string or `\0` is found or the end of
 *	  stream occurs.
 *
 * @param delimiter The delimiter
 * @return The line that was read, autoreleased, or nil if the end of the
 * @return The line that was read, autoreleased, or `nil` if the end of the
 *	   stream has been reached.
 */
- (nullable OFString*)readTillDelimiter: (OFString*)delimiter;

/*!
 * @brief Reads until the specified string or \\0 is found or the end of stream
 *	  occurs.
 * @brief Reads until the specified string or `\0` is found or the end of
 *	  stream occurs.
 *
 * @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
 * @return The line that was read, autoreleased, or `nil` if the end of the
 *	   stream has been reached.
 */
- (nullable 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.
 * @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
 * @return The line that was read, autoreleased, or `nil` if the end of the
 *	   stream has been reached.
 */
- (nullable OFString*)tryReadTillDelimiter: (OFString*)delimiter;

/*!
 * @brief Tries to read until the specified string or \\0 is found or the end
 *	  of stream occurs (see @ref readTillDelimiter:encoding:) and
 *	  returns nil if not enough data has been received yet.
 * @brief Tries to read until the specified string or `\0` is found or the end
 *	  of stream occurs (see @ref readTillDelimiter:encoding:) 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
 * @return The line that was read, autoreleased, or `nil` if the end of the
 *	   stream has been reached.
 */
- (nullable OFString*)tryReadTillDelimiter: (OFString*)delimiter
				  encoding: (of_string_encoding_t)encoding;

/*!
 * @brief Returns a boolen whether writes are buffered.

 *	  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
 * 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
 * @return A substitution for the entity or `nil`
 */
-	   (OFString*)string: (OFString*)string
  containsUnknownEntityNamed: (OFString*)entity;
@end

@interface OFString (XMLUnescaping)
/*!

 * @return The path where user configuration for the application can be stored
 */
+ (OFString*)userConfigPath;

/*!
 * @brief Returns the vendor of the CPU.
 *
 * If the vendor could not be determined, nil is returned instead.
 * If the vendor could not be determined, `nil` is returned instead.
 *
 * @return The vendor of the CPU
 */
+ (nullable OFString*)CPUVendor;

#if defined(OF_X86_64) || defined(OF_X86) || defined(DOXYGEN)
/*!

#ifdef OF_HAVE_BLOCKS
/*!
 * @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
 *		    `nil` on success
 */
typedef void (^of_tcp_socket_async_connect_block_t)(OFTCPSocket *socket,
    OFException *_Nullable 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
 *		    `nil` on success
 * @return A bool whether the same block should be used for the next incoming
 *	   connection
 */
typedef bool (^of_tcp_socket_async_accept_block_t)(OFTCPSocket *socket,
    OFTCPSocket *acceptedSocket, OFException *_Nullable exception);
#endif

/*!
 * @brief Initiates the TLS handshake.
 *
 * @note This is only useful if you used @ref initWithSocket: to start TLS on
 *	 a TCP socket which is already connected!
 *
 * @param host The host to expect for certificate verification.
 *	       May be nil if certificate verification is disabled.
 *	       May be `nil` if certificate verification is disabled.
 */
- (void)startTLSWithExpectedHost: (nullable OFString*)host;

/*!
 * @brief Sets a delegate for the TLS socket.
 *
 * @param delegate The delegate to use

 * @brief Yields a processor voluntarily and moves the thread to the end of the
 *	  queue for its priority.
 */
+ (void)yield;

#ifdef OF_HAVE_THREADS
/*!
 * @brief Terminates the current thread, letting it return nil.
 * @brief Terminates the current thread, letting it return `nil`.
 */
+ (void)terminate OF_NO_RETURN;

/*!
 * @brief Terminates the current thread, letting it return the specified object.
 *
 * @param object The object which the terminated thread will return

 * @brief Returns the run loop for the thread.
 *
 * @return The run loop for the thread
 */
- (OFRunLoop*)runLoop;

/*!
 * @brief Returns the name of the thread or nil if none has been set.
 * @brief Returns the name of the thread or `nil` if none has been set.
 *
 * @return The name of the thread or nik if none has been set
 */
- (nullable OFString*)name;

/*!
 * @brief Sets the name for the thread.

/*!
 * @brief A block which is called when the host / port pair for the UDP socket
 *	  has been resolved.
 *
 * @param host The host that has been resolved
 * @param port The port of the host / port pair
 * @param address The address of the resolved host / port pair
 * @param exception An exception which occurred while resolving or nil on
 * @param exception An exception which occurred while resolving or `nil` on
 *		    success
 */
typedef void (^of_udp_socket_async_resolve_block_t)(OFString *host,
    uint16_t port, of_udp_socket_address_t address,
    OFException *_Nullable exception);

/*!
 * @brief A block which is called when a packet has been received.
 *
 * @param socket The UDP which received a packet
 * @param buffer The buffer the packet has been written to
 * @param length The length of the packet
 * @param sender The address of the sender of the packet
 * @param exception An exception which occurred while receiving or nil on
 * @param exception An exception which occurred while receiving or `nil` on
 *		    success
 * @return A bool whether the same block should be used for the next receive
 */
typedef bool (^of_udp_socket_async_receive_block_t)(OFUDPSocket *socket,
    void *buffer, size_t length, of_udp_socket_address_t sender,
    OFException *_Nullable exception);
#endif

/*!
 * @brief This callback is called when the XML parser found the start of a new
 *	  tag.
 *
 * @param parser The parser which found a new tag
 * @param name The name of the tag which just started
 * @param prefix The prefix of the tag which just started or nil
 * @param ns The namespace of the tag which just started or nil
 * @param prefix The prefix of the tag which just started or `nil`
 * @param ns The namespace of the tag which just started or `nil`
 * @param attributes The attributes included in the tag which just started or
 *		     nil
 *		     `nil`
 */
-    (void)parser: (OFXMLParser*)parser
  didStartElement: (OFString*)name
	   prefix: (nullable OFString*)prefix
	namespace: (nullable OFString*)ns
       attributes: (nullable OFArray OF_GENERIC(OFXMLAttribute*)*)attributes;

/*!
 * @brief This callback is called when the XML parser found the end of a tag.
 *
 * @param parser The parser which found the end of a tag
 * @param name The name of the tag which just ended
 * @param prefix The prefix of the tag which just ended or nil
 * @param ns The namespace of the tag which just ended or nil
 * @param prefix The prefix of the tag which just ended or `nil`
 * @param ns The namespace of the tag which just ended or `nil`
 */
-  (void)parser: (OFXMLParser*)parser
  didEndElement: (OFString*)name
	 prefix: (nullable OFString*)prefix
      namespace: (nullable OFString*)ns;

/*!

- (void)parser: (OFXMLParser*)parser
  foundComment: (OFString*)comment;

/*!
 * @brief This callback is called when the XML parser found an entity it
 *	  doesn't know.
 *
 * The callback is supposed to return a substitution for the entity or nil if
 * The callback is supposed to return a substitution for the entity or `nil` if
 * it is not known to the callback as well, in which case an exception will be
 * risen.
 *
 * @param parser The parser which found an unknown entity
 * @param entity The name of the entity the XML parser didn't know
 * @return A substitution for the entity or nil
 * @return A substitution for the entity or `nil`
 */
-	(OFString*)parser: (OFXMLParser*)parser
  foundUnknownEntityNamed: (OFString*)entity;
@end

/*!
 * @class OFXMLParser OFXMLParser.h ObjFW/OFXMLParser.h