@@ -22,21 +22,23 @@ @class OFDataArray; /** * \brief A base class for different types of streams. * - * WARNING: Even though the OFCopying protocol is implemented, it does - * not return an independant 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! - * - * IMPORTANT: If you want to subclass this, override _readNBytes:intoBuffer:, - * _writeNBytes:fromBuffer: and _isAtEndOfStream, but nothing else. Those are - * not defined in the headers, but do the actual work. OFStream uses those and - * does all the caching and other stuff. If you override these methods without - * the _ prefix, you *WILL* break caching and get broken results! + * \warning Even though the OFCopying protocol is implemented, it does + * not return an independant 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! + * + * \warning If you want to subclass this, override _readNBytes:intoBuffer:, + * _writeNBytes:fromBuffer: and _isAtEndOfStream, but nothing else. + * Those are not defined in the headers, but do the actual work. + * OFStream uses those and does all the caching and other stuff. If + * you override these methods without the _ prefix, you *WILL* break + * caching and get broken results! */ @interface OFStream: OFObject { char *cache; char *writeBuffer; @@ -78,11 +80,11 @@ * * Unlike readNBytes:intoBuffer:, 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 + * \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 MUST be EXACTLY this big! @@ -91,61 +93,61 @@ intoBuffer: (void*)buffer; /** * \brief Reads a uint8_t from the stream. * - * WARNING: Only call this when you know that enough data is available! + * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * * \return A uint8_t from the stream */ - (uint8_t)readInt8; /** * \brief Reads a uint16_t from the stream which is encoded in big endian. * - * WARNING: Only call this when you know that enough data is available! + * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * * \return A uint16_t from the stream in native endianess */ - (uint16_t)readBigEndianInt16; /** * \brief Reads a uint32_t from the stream which is encoded in big endian. * - * WARNING: Only call this when you know that enough data is available! + * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * * \return A uint32_t from the stream in the native endianess */ - (uint32_t)readBigEndianInt32; /** * \brief Reads a uint64_t from the stream which is encoded in big endian. * - * WARNING: Only call this when you know that enough data is available! + * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * * \return A uint64_t from the stream in the native endianess */ - (uint64_t)readBigEndianInt64; /** * \brief Reads a float from the stream which is encoded in big endian. * - * WARNING: Only call this when you know that enough data is available! + * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * * \return A float from the stream in the native endianess */ - (float)readBigEndianFloat; /** * \brief Reads a double from the stream which is encoded in big endian. * - * WARNING: Only call this when you know that enough data is available! + * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * * \return A double from the stream in the native endianess */ - (double)readBigEndianDouble; @@ -152,11 +154,11 @@ /** * \brief Reads the specified number of uint16_ts from the stream which are * encoded in big endian. * - * WARNING: Only call this when you know that enough data is available! + * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * * \param nInt16s The number of uint16_ts to read * \param buffer A buffer of sufficient size to store the specified number of * uint16_ts @@ -167,11 +169,11 @@ /** * \brief Reads the specified number of uint32_ts from the stream which are * encoded in big endian. * - * WARNING: Only call this when you know that enough data is available! + * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * * \param nInt32s The number of uint32_ts to read * \param buffer A buffer of sufficient size to store the specified number of * uint32_ts @@ -182,11 +184,11 @@ /** * \brief Reads the specified number of uint64_ts from the stream which are * encoded in big endian. * - * WARNING: Only call this when you know that enough data is available! + * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * * \param nInt64s The number of uint64_ts to read * \param buffer A buffer of sufficient size to store the specified number of * uint64_ts @@ -197,11 +199,11 @@ /** * \brief Reads the specified number of floats from the stream which are encoded * in big endian. * - * WARNING: Only call this when you know that enough data is available! + * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * * \param nFloatss The number of floats to read * \param buffer A buffer of sufficient size to store the specified number of * floats @@ -212,11 +214,11 @@ /** * \brief Reads the specified number of doubles from the stream which are * encoded in big endian. * - * WARNING: Only call this when you know that enough data is available! + * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * * \param nDoubles The number of doubles to read * \param buffer A buffer of sufficient size to store the specified number of * doubles @@ -226,51 +228,51 @@ intoBuffer: (double*)buffer; /** * \brief Reads a uint16_t from the stream which is encoded in little endian. * - * WARNING: Only call this when you know that enough data is available! + * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * * \return A uint16_t from the stream in native endianess */ - (uint16_t)readLittleEndianInt16; /** * \brief Reads a uint32_t from the stream which is encoded in little endian. * - * WARNING: Only call this when you know that enough data is available! + * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * * \return A uint32_t from the stream in the native endianess */ - (uint32_t)readLittleEndianInt32; /** * \brief Reads a uint64_t from the stream which is encoded in little endian. * - * WARNING: Only call this when you know that enough data is available! + * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * * \return A uint64_t from the stream in the native endianess */ - (uint64_t)readLittleEndianInt64; /** * \brief Reads a float from the stream which is encoded in little endian. * - * WARNING: Only call this when you know that enough data is available! + * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * * \return A float from the stream in the native endianess */ - (float)readLittleEndianFloat; /** * \brief Reads a double from the stream which is encoded in little endian. * - * WARNING: Only call this when you know that enough data is available! + * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * * \return A double from the stream in the native endianess */ - (double)readLittleEndianDouble; @@ -277,11 +279,11 @@ /** * \brief Reads the specified number of uint16_ts from the stream which are * encoded in little endian. * - * WARNING: Only call this when you know that enough data is available! + * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * * \param nInt16s The number of uint16_ts to read * \param buffer A buffer of sufficient size to store the specified number of * uint16_ts @@ -292,11 +294,11 @@ /** * \brief Reads the specified number of uint32_ts from the stream which are * encoded in little endian. * - * WARNING: Only call this when you know that enough data is available! + * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * * \param nInt32s The number of uint32_ts to read * \param buffer A buffer of sufficient size to store the specified number of * uint32_ts @@ -307,11 +309,11 @@ /** * \brief Reads the specified number of uint64_ts from the stream which are * encoded in little endian. * - * WARNING: Only call this when you know that enough data is available! + * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * * \param nInt64s The number of uint64_ts to read * \param buffer A buffer of sufficient size to store the specified number of * uint64_ts @@ -322,11 +324,11 @@ /** * \brief Reads the specified number of floats from the stream which are * encoded in little endian. * - * WARNING: Only call this when you know that enough data is available! + * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * * \param nFloats The number of floats to read * \param buffer A buffer of sufficient size to store the specified number of * floats @@ -337,11 +339,11 @@ /** * \brief Reads the specified number of doubles from the stream which are * encoded in little endian. * - * WARNING: Only call this when you know that enough data is available! + * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * * \param nDoubles The number of doubles to read * \param buffer A buffer of sufficient size to store the specified number of * doubles @@ -352,11 +354,11 @@ /** * \brief Reads the specified number of items with an item size of 1 from the * stream and returns them in an OFDataArray. * - * WARNING: Only call this when you know that enough data is available! + * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * * \param nItems The number of items to read * \return An OFDataArray with at nItems items. */ @@ -364,11 +366,11 @@ /** * \brief Reads the specified number of items with the specified item size from * the stream and returns them in an OFDataArray. * - * WARNING: Only call this when you know that enough data is available! + * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * * \param itemSize The size of each item * \param nItems The number of items to read * \return An OFDataArray with at nItems items. @@ -390,11 +392,11 @@ * 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! + * \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 */ @@ -406,11 +408,11 @@ * 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! + * \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