ObjFW  Check-in [e685b742d9]

 * @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;

/*!
 * @brief Signals all threads to continue.
 */
- (void)broadcast;
@end

 *	  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
 */

- 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

 */
+ (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.
 *

- 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.
 *

 * @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
 */

 * 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.
 *

 * @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.

 * @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;

- (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

		     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!

#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!

 * @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;

 *	   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

#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

 */
- (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;

 * @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.

 * @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

#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)

#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

- (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;

/*!
 * @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;

 * @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;

 */
- (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.

 *	    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!
 *