Initial revision of the API documentation guidelines up for discussion. DataIO.dox and List.dox conform to these guidelines.
git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@20392 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
Niels Sascha Reedijk
+265
-244
@@ -1,405 +1,426 @@
|
||||
//
|
||||
// Copyright 2007, Haiku Inc. All Rights Reserved.
|
||||
//
|
||||
// Distributed under the terms of the MIT License.
|
||||
//
|
||||
//
|
||||
// Documentation by:
|
||||
// Niels Sascha Reedijk <[email protected]>
|
||||
// Stefano Ceccherini ([email protected])
|
||||
// Corresponds to:
|
||||
// /trunk/headers/os/support/DataIO.h rev 17981
|
||||
// /trunk/src/kits/support/DataIO.cpp rev 17981
|
||||
//
|
||||
|
||||
/*!
|
||||
\file DataIO.h
|
||||
\brief Provides abstract BDataIO and BPositionIO and the derived BMallocIO and BMemoryIO classes.
|
||||
\file DataIO.h
|
||||
\brief Defines abstract BDataIO and BPositionIO and the derived BMallocIO and BMemoryIO classes.
|
||||
|
||||
Pure virtual BDataIO and BPositioIO classes provide
|
||||
the protocol for Read()/Write()/Seek().
|
||||
Pure virtual BDataIO and BPositioIO classes provide
|
||||
the protocol for Read()/Write()/Seek().
|
||||
|
||||
BMallocIO and BMemoryIO classes implement the protocol,
|
||||
as does BFile in the Storage Kit.
|
||||
BMallocIO and BMemoryIO classes implement the protocol,
|
||||
as does BFile in the Storage Kit.
|
||||
*/
|
||||
|
||||
//////////// BDataIO
|
||||
///// BDataIO /////
|
||||
|
||||
/*!
|
||||
\class BDataIO
|
||||
\ingroup support
|
||||
\ingroup libbe
|
||||
\brief Abstract interface for objects that provides read and write access to data.
|
||||
\class BDataIO
|
||||
\ingroup support
|
||||
\ingroup libbe
|
||||
\brief Abstract interface for objects that provide read and write access to
|
||||
data.
|
||||
|
||||
The interface provided by this class applies to objects or data that are
|
||||
limited to reading and writing data. Classes derived from this class should
|
||||
reimplement both the Read() and Write() method from this class.
|
||||
The interface provided by this class applies to objects or data that are
|
||||
limited to reading and writing data. Classes derived from this class should
|
||||
reimplement both the Read() and Write() method from this class.
|
||||
|
||||
Candidates of types of data or objects that should be derived from this class
|
||||
are probably broadcasting media streams (which don't support reading at a
|
||||
certain point in the data) or network streams that output data continously.
|
||||
Objects and data that support more advanced operations like seeking or
|
||||
reading at writing at defined positions should derive their classes from
|
||||
BPositionIO, which inherits this class.
|
||||
Candidates of types of data or objects that should be derived from this class
|
||||
are probably broadcasting media streams (which don't support reading at a
|
||||
certain point in the data) or network streams that output data continously.
|
||||
Objects and data that support more advanced operations like seeking or
|
||||
reading at writing at defined positions should derive their classes from
|
||||
BPositionIO, which inherits this class.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn BDataIO::BDataIO()
|
||||
\brief This constructor does nothing.
|
||||
\fn BDataIO::BDataIO()
|
||||
\brief This constructor does nothing.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn BDataIO::~BDataIO()
|
||||
\brief This destructor does nothing.
|
||||
\fn BDataIO::~BDataIO()
|
||||
\brief This destructor does nothing.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn virtual ssize_t BDataIO::Read(void *buffer, size_t size) = 0
|
||||
\brief Pure virtual to read data.
|
||||
\fn virtual ssize_t BDataIO::Read(void *buffer, size_t size) = 0
|
||||
\brief Pure virtual to read data.
|
||||
|
||||
Your implementation should copy data into \c buffer, with the maximum size
|
||||
of \c size.
|
||||
\return You should return the amount of bytes actually read, or an error code
|
||||
in case of failure.
|
||||
Your implementation should copy data into \c buffer, with the maximum size
|
||||
of \c size.
|
||||
\return You should return the amount of bytes actually read, or an error code
|
||||
in case of failure.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn virtual ssize_t BDataIO::Write(const void *buffer, size_t size) = 0
|
||||
\brief Pure virtual to write data.
|
||||
\fn virtual ssize_t BDataIO::Write(const void *buffer, size_t size) = 0
|
||||
\brief Pure virtual to write data.
|
||||
|
||||
Your implementation should copy data from \c buffer, with the maximum size
|
||||
of \c size.
|
||||
\return You should return the amount of bytes actually written, or an error code
|
||||
in case of failure.
|
||||
Your implementation should copy data from \c buffer, with the maximum size
|
||||
of \c size.
|
||||
\return You should return the amount of bytes actually written, or an error
|
||||
code in case of failure.
|
||||
*/
|
||||
|
||||
//////////// BPositionIO
|
||||
/*!
|
||||
\class BPositionIO
|
||||
\ingroup support
|
||||
\ingroup libbe
|
||||
\brief Abstract interface that provides advanced read, write and seek access to data.
|
||||
\class BPositionIO
|
||||
\ingroup support
|
||||
\ingroup libbe
|
||||
\brief Abstract interface that provides advanced read, write and seek access
|
||||
to data.
|
||||
|
||||
The interface of this object applies to objects or data that allows
|
||||
position-aware reading and writing of data. Classes that derive from this
|
||||
class should at least reimplement ReadAt(), WriteAt(), Seek(), Position(),
|
||||
SetSize() and GetSize() methods.
|
||||
The interface of this object applies to objects or data that allows
|
||||
position-aware reading and writing of data. Classes that derive from this
|
||||
class should at least reimplement ReadAt(), WriteAt(), Seek(), Position(),
|
||||
SetSize() and GetSize() methods.
|
||||
|
||||
A good example of a form of data that can derive from this object, are files.
|
||||
The BFile class derives from BPositionIO and provides this interface to files.
|
||||
If your object or data only supports linear reading and writing, consider
|
||||
deriving from the baseclass BDataIO.
|
||||
A good example of a form of data that can derive from this object, are files.
|
||||
The BFile class derives from BPositionIO and provides this interface to
|
||||
files. If your object or data only supports linear reading and writing,
|
||||
consider deriving from the baseclass BDataIO.
|
||||
|
||||
A final note, from BDataIO this class inherits Read() and Write(). The default
|
||||
implementation is to read or write the data at the current position indicated
|
||||
by Position(). Reimplement the methods if you require a different behaviour.
|
||||
A final note, from BDataIO this class inherits Read() and Write(). The
|
||||
default implementation is to read or write the data at the current position
|
||||
indicated by Position(). Reimplement the methods if you require a different
|
||||
behaviour.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn BPositionIO::BPositionIO()
|
||||
\brief This constructor does nothing.
|
||||
\fn BPositionIO::BPositionIO()
|
||||
\brief This constructor does nothing.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn virtual BPositionIO::~BPositionIO()
|
||||
\brief This destructor does nothing.
|
||||
\fn virtual BPositionIO::~BPositionIO()
|
||||
\brief This destructor does nothing.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn virtual ssize_t BPositionIO::Read(void *buffer, size_t size)
|
||||
\brief Read data from current position.
|
||||
\fn virtual ssize_t BPositionIO::Read(void *buffer, size_t size)
|
||||
\brief Read data from current position.
|
||||
|
||||
This method is derived from BDataIO. The default implementation reads data from
|
||||
the current position of the cursor, pointed at by Position(). If you require
|
||||
different behaviour, please look at BDataIO::Read() for what is expected of
|
||||
this method.
|
||||
This method is derived from BDataIO. The default implementation reads data
|
||||
from the current position of the cursor, pointed at by Position(). If you
|
||||
require different behaviour, please look at BDataIO::Read() for what is
|
||||
expected of this method.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn virtual ssize_t BPositionIO::Write(const void *buffer, size_t size)
|
||||
\brief Write data to the current position.
|
||||
\fn virtual ssize_t BPositionIO::Write(const void *buffer, size_t size)
|
||||
\brief Write data to the current position.
|
||||
|
||||
This method is derived from BDataIO. The default implementation writes data to
|
||||
the current position of the cursor, pointed at by Position(). If you require
|
||||
different behaviour, please look at BDataIO::Write() for what is expected of
|
||||
this method.
|
||||
This method is derived from BDataIO. The default implementation writes data
|
||||
to the current position of the cursor, pointed at by Position(). If you
|
||||
require different behaviour, please look at BDataIO::Write() for what is
|
||||
expected of this method.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn virtual ssize_t BPositionIO::ReadAt(off_t position, void *buffer, size_t size) = 0
|
||||
\brief Pure virtual to read data from a certain position.
|
||||
\fn virtual ssize_t BPositionIO::ReadAt(off_t position, void *buffer, size_t size) = 0
|
||||
\brief Pure virtual to read data from a certain position.
|
||||
|
||||
Your implementation should copy data from the position indicated by \c position
|
||||
into the \c buffer with the maximum size of \c size.
|
||||
Your implementation should copy data from the position indicated by
|
||||
\a position into the \a buffer with the maximum size of \a size.
|
||||
|
||||
\return The amount of bytes actually read, or an error code.
|
||||
\return The amount of bytes actually read, or an error code.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn virtual ssize_t BPositionIO::WriteAt(off_t position, const void *buffer, size_t size) = 0
|
||||
\brief Pure virtual to write data to a certain position.
|
||||
\fn virtual ssize_t BPositionIO::WriteAt(off_t position, const void *buffer, size_t size) = 0
|
||||
\brief Pure virtual to write data to a certain position.
|
||||
|
||||
Your implementation should copy data from \c buffer to the position indicated
|
||||
by \c buffer with the maximum size of \c size.
|
||||
Your implementation should copy data from \a buffer to the position indicated
|
||||
by \a buffer with the maximum size of \a size.
|
||||
|
||||
\return The amount of bytes actually written, or an error code.
|
||||
\return The amount of bytes actually written, or an error code.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn virtual off_t BPositionIO::Seek(off_t position, uint32 seekMode) = 0
|
||||
\brief Pure virtual to move the cursor to a certain position.
|
||||
\fn virtual off_t BPositionIO::Seek(off_t position, uint32 seekMode) = 0
|
||||
\brief Pure virtual to move the cursor to a certain position.
|
||||
|
||||
Your implementation should move the position of the cursor to the provided
|
||||
point. What this actually means, depends on your object or data.
|
||||
Your implementation should move the position of the cursor to the provided
|
||||
point. What this actually means, depends on your object or data.
|
||||
|
||||
\param position An integer that defines a position.
|
||||
\param seekMode You will get one of the following values:
|
||||
- \c SEEK_SET Set the cursor to the position indicated by \c position.
|
||||
- \c SEEK_END Set the cursor to the end of the buffer, and go
|
||||
\c position beyond that.
|
||||
- \c SEEK_CUR Set the cursor the the current position plus \c position.
|
||||
\return The new position.
|
||||
\param position An integer that defines a position.
|
||||
\param seekMode You will get one of the following values:
|
||||
- \c SEEK_SET Set the cursor to the position indicated by \c position.
|
||||
- \c SEEK_END Set the cursor to the end of the buffer, and go
|
||||
\c position beyond that.
|
||||
- \c SEEK_CUR Set the cursor the the current position plus \c position.
|
||||
\return The new position.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn virtual off_t BPositionIO::Position() const = 0
|
||||
\brief Pure virtual to return the current position of the cursor.
|
||||
\fn virtual off_t BPositionIO::Position() const = 0
|
||||
\brief Pure virtual to return the current position of the cursor.
|
||||
|
||||
\return
|
||||
Your implementation should return the current position of the cursor.
|
||||
\return Your implementation should return the current position of the cursor.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn virtual status_t BPositionIO::SetSize(off_t size)
|
||||
\brief Set the size of the object or data.
|
||||
\fn virtual status_t BPositionIO::SetSize(off_t size)
|
||||
\brief Set the size of the object or data.
|
||||
|
||||
The default implementation returns \c B_ERROR. If your object or data allows
|
||||
the size to be changed, reimplement this method.
|
||||
The default implementation returns \c B_ERROR. If your object or data allows
|
||||
the size to be changed, reimplement this method.
|
||||
|
||||
\return Return \c B_OK if everything succeeded, else return the appropriate
|
||||
error code.
|
||||
\return Return \c B_OK if everything succeeded, else return the appropriate
|
||||
error code.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn virtual status_t BPositionIO::GetSize(off_t* size) const
|
||||
\brief Get the size of the object or data.
|
||||
\fn virtual status_t BPositionIO::GetSize(off_t* size) const
|
||||
\brief Get the size of the object or data.
|
||||
|
||||
The default implementation uses Seek() with the \c SEEK_END flag to
|
||||
determine the size of the buffer. If your data or object has a different way
|
||||
of determining size, reimplement this method.
|
||||
The default implementation uses Seek() with the \c SEEK_END flag to
|
||||
determine the size of the buffer. If your data or object has a different way
|
||||
of determining size, reimplement this method.
|
||||
|
||||
Please check that NULL is not passed into \c size if you reimplement it in
|
||||
your class.
|
||||
Please check that NULL is not passed into \c size if you reimplement it in
|
||||
your class.
|
||||
|
||||
\param[out] size The size of the object is put into this parameter.
|
||||
\return This method returns \c B_OK on success or an error code on error.
|
||||
\sa Seek()
|
||||
\param[out] size The size of the object is put into this parameter.
|
||||
\return This method returns \c B_OK on success or an error code on error.
|
||||
\see Seek()
|
||||
*/
|
||||
|
||||
//////////// BMemoryIO
|
||||
/*!
|
||||
\class BMemoryIO
|
||||
\ingroup support
|
||||
\ingroup libbe
|
||||
\brief A BPositionIO derived class that works on memory buffers.
|
||||
\class BMemoryIO
|
||||
\ingroup support
|
||||
\ingroup libbe
|
||||
\brief A BPositionIO derived class that works on memory buffers.
|
||||
|
||||
This class is used if you require access that confirms to the BPositionIO
|
||||
interface on memory buffers that you created. If you would like to use that
|
||||
interface on new buffers, have a look at BMallocIO.
|
||||
This class is used if you require access that confirms to the BPositionIO
|
||||
interface on memory buffers that you created. If you would like to use that
|
||||
interface on new buffers, have a look at BMallocIO.
|
||||
|
||||
This class is particularly useful if you would like to use a class or method
|
||||
that are written to make use of the BPositionIO interface. It might also
|
||||
be used for 'secure' reading and writing from buffers, since this class
|
||||
automatically checks the bounds of anything you might want to do.
|
||||
This class is particularly useful if you would like to use a class or method
|
||||
that are written to make use of the BPositionIO interface. It might also
|
||||
be used for 'secure' reading and writing from buffers, since this class
|
||||
automatically checks the bounds of anything you might want to do.
|
||||
|
||||
This class reimplements the Read(), Write(), ReadAt(), Writeat(), Seek() and
|
||||
Position() interface from BPositionIO.
|
||||
This class reimplements the Read(), Write(), ReadAt(), Writeat(), Seek() and
|
||||
Position() interface from BPositionIO.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn BMemoryIO::BMemoryIO(void *data, size_t length)
|
||||
\brief Create a read/write object.
|
||||
\fn BMemoryIO::BMemoryIO(void *data, size_t length)
|
||||
\brief Create a read/write object.
|
||||
|
||||
\param data A pointer to the buffer to adopt.
|
||||
\param length The size of the buffer.
|
||||
\sa BMemoryIO(const void *buffer, size_t length) for a read-only implementation.
|
||||
\param data A pointer to the buffer to adopt.
|
||||
\param length The size of the buffer.
|
||||
\see BMemoryIO(const void *buffer, size_t length) for a read-only
|
||||
implementation.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn BMemoryIO::BMemoryIO(const void *buffer, size_t length)
|
||||
\brief Create a read-only object.
|
||||
\fn BMemoryIO::BMemoryIO(const void *buffer, size_t length)
|
||||
\brief Create a read-only object.
|
||||
|
||||
\param buffer A pointer to the \c const (read-only) buffer to adopt.
|
||||
\param length The size of the buffer.
|
||||
\sa BMemoryIO(void *buffer, size_t length) for a read-write implementation.
|
||||
\param buffer A pointer to the \c const (read-only) buffer to adopt.
|
||||
\param length The size of the buffer.
|
||||
\see BMemoryIO(void *buffer, size_t length) for a read-write implementation.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn BMemoryIO::~BMemoryIO()
|
||||
\brief The destructor does nothing.
|
||||
\fn BMemoryIO::~BMemoryIO()
|
||||
\brief The destructor does nothing.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn ssize_t BMemoryIO::ReadAt(off_t pos, void *buffer, size_t size)
|
||||
\brief Read from a given position.
|
||||
\fn ssize_t BMemoryIO::ReadAt(off_t pos, void *buffer, size_t size)
|
||||
\brief Read from a given position.
|
||||
|
||||
\param[in] pos The offset where to start reading data.
|
||||
\param[out] buffer The buffer to copy the read bytes into.
|
||||
\param[in] size The size of the \c buffer.
|
||||
\return The amount of read bytes or an error code.
|
||||
\retval B_BAD_VALUE The position is less than zero or the buffer given on
|
||||
construction is invalid.
|
||||
\param[in] pos The offset where to start reading data.
|
||||
\param[out] buffer The buffer to copy the read bytes into.
|
||||
\param[in] size The size of the \a buffer.
|
||||
\return The amount of read bytes or an error code.
|
||||
\retval B_BAD_VALUE The position is less than zero or the buffer given on
|
||||
construction is invalid.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn ssize_t BMemoryIO::WriteAt(off_t pos, const void *buffer, size_t size)
|
||||
\brief Write to a given position.
|
||||
\fn ssize_t BMemoryIO::WriteAt(off_t pos, const void *buffer, size_t size)
|
||||
\brief Write at a given position.
|
||||
|
||||
\param pos The offset to write to.
|
||||
\param buffer The buffer to copy the bytes from.
|
||||
\param size The number of bytes to write.
|
||||
\return The amount of bytes written or an error code.
|
||||
\retval B_NOT_ALLOWED The object is constructed as a read-only object.
|
||||
\retval B_BAD_VALUE The position is less than zero or the buffer given on
|
||||
construction is invalid.
|
||||
\param pos The offset to write to.
|
||||
\param buffer The buffer to copy the bytes from.
|
||||
\param size The number of bytes to write.
|
||||
\return The amount of bytes written or an error code.
|
||||
\retval B_NOT_ALLOWED The object is constructed as a read-only object.
|
||||
\retval B_BAD_VALUE The position is less than zero or the buffer given on
|
||||
construction is invalid.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn off_t BMemoryIO::Seek(off_t position, uint32 seek_mode)
|
||||
\brief Move the cursor to a given position.
|
||||
\fn off_t BMemoryIO::Seek(off_t position, uint32 seek_mode)
|
||||
\brief Move the cursor to a given position.
|
||||
|
||||
\param position The position to move the cursor to.
|
||||
\param seek_mode The mode determines where the cursor is placed. Possibilities:
|
||||
- \c SEEK_SET The cursor is set to \c position.
|
||||
- \c SEEK_CUR The \c position is added to the current position of the cursor.
|
||||
- \c SEEK_END The cursor is put at the end of the data, plus
|
||||
\c position added to it.
|
||||
\return The new position.
|
||||
\param position The position to move the cursor to.
|
||||
\param seek_mode The mode determines where the cursor is placed.
|
||||
Possibilities:
|
||||
- \c SEEK_SET The cursor is set to \a position.
|
||||
- \c SEEK_CUR The \a position is added to the current position of the
|
||||
cursor.
|
||||
- \c SEEK_END The cursor is put at the end of the data, plus
|
||||
\a position added to it.
|
||||
\return The new position.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn off_t BMemoryIO::Position() const
|
||||
\brief Return the current position.
|
||||
\fn off_t BMemoryIO::Position() const
|
||||
\brief Return the current position.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn status_t BMemoryIO::SetSize(off_t size)
|
||||
\brief Resize the buffer.
|
||||
\fn status_t BMemoryIO::SetSize(off_t size)
|
||||
\brief Resize the buffer.
|
||||
|
||||
This method does not actually resize the buffer. If the new size is greater
|
||||
than the size of the buffer, resizing will fail. It will only succeed if the new
|
||||
size is less than the size of the buffer. The buffer itself will not be resized
|
||||
though.
|
||||
This method does not actually resize the buffer. If the new size is greater
|
||||
than the size of the buffer, resizing will fail. It will only succeed if the
|
||||
new size is less than the size of the buffer. The buffer itself will not be
|
||||
resized though.
|
||||
|
||||
This method might be useful in some cases. If the buffer is larger than the
|
||||
data it holds, changing the size will enable you to use the Seek() method
|
||||
with the flag \c SEEK_END and not get an error if you read or write from
|
||||
that position, since you actually have a buffer at the end.
|
||||
This method might be useful in some cases. If the buffer is larger than the
|
||||
data it holds, changing the size will enable you to use the Seek() method
|
||||
with the flag \c SEEK_END and not get an error if you read or write from
|
||||
that position, since you actually have a buffer at the end.
|
||||
|
||||
\retval B_OK The buffer is resized.
|
||||
\retval B_NOT_ALLOWED The buffer is read-only.
|
||||
\retval B_ERROR The \c size is larger than the size of the buffer.
|
||||
\retval B_OK The buffer is resized.
|
||||
\retval B_NOT_ALLOWED The buffer is read-only.
|
||||
\retval B_ERROR The \c size is larger than the size of the buffer.
|
||||
*/
|
||||
|
||||
//////////// BMallocIO
|
||||
/*!
|
||||
\class BMallocIO
|
||||
\ingroup support
|
||||
\ingroup libbe
|
||||
\brief A BPositionIO derived class that creates a memory buffer.
|
||||
\class BMallocIO
|
||||
\ingroup support
|
||||
\ingroup libbe
|
||||
\brief A BPositionIO derived class that creates a memory buffer.
|
||||
|
||||
This class creates a memory buffer and provides a BPositionIO interface to work
|
||||
on it. The memory buffer grows and shrinks automatically.
|
||||
This is especially useful if you want to use a method or function that
|
||||
works on an object derived from BPositionIO and you want to do something with
|
||||
the resulting data, or it could be useful if you want to read and write to
|
||||
memory in a safe way, since this class has boundary checking.
|
||||
This class creates a memory buffer and provides a BPositionIO interface to
|
||||
work on it. The memory buffer grows and shrinks automatically.
|
||||
This is especially useful if you want to use a method or function that
|
||||
works on an object derived from BPositionIO and you want to do something with
|
||||
the resulting data, or it could be useful if you want to read and write to
|
||||
memory in a safe way, since this class has boundary checking.
|
||||
|
||||
BMallocIO allocates a buffer based on a certain blocksize. This provides a
|
||||
mechanism that will prevent it from needing to allocate new memory too often.
|
||||
The default blocksize is 256 bytes, you can change it with SetBlockSize(). If you
|
||||
are sure you are going to use a bigger buffer, change the blocksize so that
|
||||
you won't have to allocate more memory too often, especially if you use this
|
||||
class in performance-critical code.
|
||||
BMallocIO allocates a buffer based on a certain blocksize. This provides a
|
||||
mechanism that will prevent it from needing to allocate new memory too often.
|
||||
The default blocksize is 256 bytes, you can change it with SetBlockSize(). If
|
||||
you are sure you are going to use a bigger buffer, change the blocksize so
|
||||
that you won't have to allocate more memory too often, especially if you use
|
||||
this class in performance-critical code.
|
||||
|
||||
If you require a BPositionIO derived object that works on buffers you provide,
|
||||
have a look at BMemoryIO.
|
||||
If you require a BPositionIO derived object that works on buffers you
|
||||
provide, have a look at BMemoryIO.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn BMallocIO::BMallocIO()
|
||||
\brief Create a new memory buffer with block size 256.
|
||||
\sa SetBlockSize()
|
||||
\fn BMallocIO::BMallocIO()
|
||||
\brief Create a new memory buffer with block size 256.
|
||||
\see SetBlockSize()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn BMallocIO::~BMallocIO()
|
||||
\brief Destroy the object and free the internal buffer.
|
||||
\fn BMallocIO::~BMallocIO()
|
||||
\brief Destroy the object and free the internal buffer.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn ssize_t BMallocIO::ReadAt(off_t pos, void *buffer, size_t size)
|
||||
\brief Read data at a certain position.
|
||||
\fn ssize_t BMallocIO::ReadAt(off_t pos, void *buffer, size_t size)
|
||||
\brief Read data at a certain position.
|
||||
|
||||
\param[in] pos Offset into the data where to read from.
|
||||
\param[out] buffer The buffer to copy the read bytes in.
|
||||
\param [in] size Size of the buffer.
|
||||
\return The number of read bytes, or \c B_BAD_VALUE if
|
||||
the provided \c buffer is invalid.
|
||||
\param[in] pos Offset into the data where to read from.
|
||||
\param[out] buffer The buffer to copy the read bytes in.
|
||||
\param [in] size Size of the buffer.
|
||||
\return The number of read bytes, or \c B_BAD_VALUE if
|
||||
the provided \a buffer is invalid.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn ssize_t BMallocIO::WriteAt(off_t pos, const void *buffer, size_t size)
|
||||
\brief Write data to a certain position.
|
||||
\fn ssize_t BMallocIO::WriteAt(off_t pos, const void *buffer, size_t size)
|
||||
\brief Write data to a certain position.
|
||||
|
||||
\param pos Offset into the data where to write to.
|
||||
\param buffer The buffer to copy from.
|
||||
\param size The size of the buffer.
|
||||
\return The number of bytes written or \c B_BAD_VALUE if the provided \c buffer
|
||||
is invalid.
|
||||
\param pos Offset into the data where to write to.
|
||||
\param buffer The buffer to copy from.
|
||||
\param size The size of the buffer.
|
||||
\return The number of bytes written or \c B_BAD_VALUE if the provided.
|
||||
\a buffer is invalid.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn off_t BMallocIO::Seek(off_t position, uint32 seekMode)
|
||||
\brief Move the cursor to a given position.
|
||||
\fn off_t BMallocIO::Seek(off_t position, uint32 seekMode)
|
||||
\brief Move the cursor to a given position.
|
||||
|
||||
\param position The position to move the cursor to.
|
||||
\param seekMode The mode determines where the cursor is placed. Possibilities:
|
||||
- \c SEEK_SET The cursor is set to \c position.
|
||||
- \c SEEK_CUR The \c position is added to the current position of the cursor.
|
||||
- \c SEEK_END The cursor is put at the end of the data, plus
|
||||
\c position added to it.
|
||||
\return The new position.
|
||||
\param position The position to move the cursor to.
|
||||
\param seekMode The mode determines where the cursor is placed. Possibilities:
|
||||
- \c SEEK_SET The cursor is set to \a position.
|
||||
- \c SEEK_CUR The \c position is added to the current position of the
|
||||
cursor.
|
||||
- \c SEEK_END The cursor is put at the end of the data, plus
|
||||
\a position added to it.
|
||||
\return The new position.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn off_t BMallocIO::Position() const
|
||||
\brief Return the position of the cursor.
|
||||
\fn off_t BMallocIO::Position() const
|
||||
\brief Return the position of the cursor.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn status_t BMallocIO::SetSize(off_t size)
|
||||
\brief Change the size of the buffer.
|
||||
\fn status_t BMallocIO::SetSize(off_t size)
|
||||
\brief Change the size of the buffer.
|
||||
|
||||
This method changes the size of the current buffer. If \c size is smaller than
|
||||
the current size, the data will be cleared.
|
||||
This method changes the size of the current buffer. If \a size is smaller
|
||||
than the current size, the data will be cleared.
|
||||
|
||||
\param size The new size of the buffer.
|
||||
\retval B_OK Resizing the data succeeded.
|
||||
\retval B_NO_MEMORY Failed to allocate the necessary memory.
|
||||
\param size The new size of the buffer.
|
||||
\retval B_OK Resizing the data succeeded.
|
||||
\retval B_NO_MEMORY Failed to allocate the necessary memory.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BMallocIO::SetBlockSize(size_t blockSize)
|
||||
\brief Change the block size to a certain value.
|
||||
\fn void BMallocIO::SetBlockSize(size_t blockSize)
|
||||
\brief Change the block size to a certain value.
|
||||
|
||||
This class allocates memory in blocks. If you are in performance-critical code
|
||||
you might want to tweak this setting to create a better performance in case you
|
||||
know you are going to allocate more than the default blocksize of 256.
|
||||
This class allocates memory in blocks. If you are in performance-critical
|
||||
code you might want to tweak this setting to create a better performance in
|
||||
case you know you are going to allocate more than the default blocksize of
|
||||
256.
|
||||
|
||||
\param blockSize The new block size.
|
||||
\param blockSize The new block size.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn const void *BMallocIO::Buffer() const
|
||||
\brief Return a pointer to the internal buffer.
|
||||
\fn const void *BMallocIO::Buffer() const
|
||||
\brief Return a pointer to the internal buffer.
|
||||
|
||||
As with any pointer to internal buffers you can retrieve with the Haiku API,
|
||||
make sure you don't change anything since it doesn't belong to you.
|
||||
As with any pointer to internal buffers the Haiku API exposes,
|
||||
make sure you don't change anything since it doesn't belong to you.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn size_t BMallocIO::BufferLength() const
|
||||
\brief Return the number of bytes in the buffer.
|
||||
\fn size_t BMallocIO::BufferLength() const
|
||||
\brief Return the number of bytes in the buffer.
|
||||
|
||||
This number doesn't have to be the same size as the buffer is. Because memory
|
||||
is allocated in blocks the actual size of the buffer may be greater, but this
|
||||
method only returns the number of bytes that are actually used.
|
||||
This number doesn't have to be the same size as the buffer is. Because memory
|
||||
is allocated in blocks the actual size of the buffer may be greater, but this
|
||||
method only returns the number of bytes that are actually used.
|
||||
*/
|
||||
|
||||
|
||||
+203
-187
@@ -1,352 +1,368 @@
|
||||
//
|
||||
// Copyright 2007, Haiku Inc. All Rights Reserved.
|
||||
//
|
||||
// Distributed under the terms of the MIT License.
|
||||
//
|
||||
//
|
||||
// Documentation by:
|
||||
// Niels Sascha Reedijk <[email protected]>
|
||||
// Niels Sascha Reedijk <[email protected]
|
||||
// Corresponds to:
|
||||
// /trunk/headers/os/support/List.h rev 19972
|
||||
// /trunk/src/kits/support/List.cpp rev 18649
|
||||
//
|
||||
|
||||
/*!
|
||||
\file List.h
|
||||
\brief Implements a list implementation.
|
||||
\file List.h
|
||||
\brief Defines the BList class.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\class BList
|
||||
\ingroup support
|
||||
\ingroup libbe
|
||||
\brief An ordered container that is designed to hold generic \c void * objects.
|
||||
\class BList
|
||||
\ingroup support
|
||||
\ingroup libbe
|
||||
\brief An ordered container that is designed to hold generic \c void *
|
||||
objects.
|
||||
|
||||
This class is designed to be used for a variety of tasks. Unlike similar
|
||||
implementations in other libraries, this class is not based on templates,
|
||||
and as such is inherently not typed. So it will be the job of the coder to
|
||||
make sure proper data will be entered, since the compiler cannot check this.
|
||||
This class is designed to be used for a variety of tasks. Unlike similar
|
||||
implementations in other libraries, this class is not based on templates,
|
||||
and as such is inherently not typed. So it will be the job of the coder to
|
||||
make sure proper data will be entered, since the compiler cannot check this.
|
||||
|
||||
BList contains a list of items that will grow and shrink depending on
|
||||
how much items are in it. So you will not have to do any of the
|
||||
memory management. Furthermore, it's ordered. Those properties make it
|
||||
useful in a whole range of situations, for example in the interface kit in
|
||||
the BListView class.
|
||||
BList contains a list of items that will grow and shrink depending on
|
||||
how much items are in it. So you will not have to do any of the
|
||||
memory management. Furthermore, it's ordered. Those properties make it
|
||||
useful in a whole range of situations, for example in the interface kit in
|
||||
the BListView class.
|
||||
|
||||
A note on ownership of the objects might come in handy. BList at no time
|
||||
assumes ownership of the objects, so removing items from the list will
|
||||
only remove those items from the list, it will not delete the item. In the
|
||||
same spirit you should also make sure that before you might delete an
|
||||
object that's in a list, you will remove it from the list first.
|
||||
A note on ownership of the objects might come in handy. BList at no time
|
||||
assumes ownership of the objects, so removing items from the list will
|
||||
only remove those items from the list, it will not delete the item. In the
|
||||
same spirit you should also make sure that before you might delete an
|
||||
object that's in a list, you will remove it from the list first.
|
||||
|
||||
\warning This class is not thread-safe.
|
||||
\warning This class is not thread-safe.
|
||||
|
||||
The class implements methods to add and remove items, reorder items,
|
||||
retrieve items, querying for items and some advanced methods which let
|
||||
you perform a certain tasks to all the items of the list.
|
||||
The class implements methods to add and remove items, reorder items,
|
||||
retrieve items, querying for items and some advanced methods which let
|
||||
you perform a certain tasks to all the items of the list.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn BList::BList(int32 count = 20)
|
||||
\brief Create a new list with a number of empty slots.
|
||||
\fn BList::BList(int32 count = 20)
|
||||
\brief Create a new list with a number of empty slots.
|
||||
|
||||
The memory management of this class allocates new memory per block. The
|
||||
\c count parameter can be tweaked to determine the size of those blocks.
|
||||
In general, if you know your list is only going to contain a fixed maximum
|
||||
number of items, pass that value. If you expect your list to have very few items,
|
||||
it's probably safe to choose a low number. This is as to prevent the list from
|
||||
taking up unneccesary memory. If you expect the list to contain a large
|
||||
number of items, choose a higher value, since every time the memory is full, all
|
||||
the items have to be copied into a new piece of allocated memory which is
|
||||
an expensive operation.
|
||||
The memory management of this class allocates new memory per block. The
|
||||
\c count parameter can be tweaked to determine the size of those blocks.
|
||||
In general, if you know your list is only going to contain a fixed maximum
|
||||
number of items, pass that value. If you expect your list to have very few
|
||||
items, it's probably safe to choose a low number. This is as to prevent the
|
||||
list from taking up unneccesary memory. If you expect the list to contain a
|
||||
large number of items, choose a higher value, since every time the memory is
|
||||
full, all the items have to be copied into a new piece of allocated memory
|
||||
which is an expensive operation.
|
||||
|
||||
If you are unsure, you don't have to break your head over this. As long as you
|
||||
don't use a lot of lists or as long as the list isn't used in one of the
|
||||
performance critical parts of the code, you are safe to go with the default
|
||||
value.
|
||||
If you are unsure, you don't have to break your head over this. As long as
|
||||
you don't use a lot of lists or as long as the list isn't used in one of the
|
||||
performance critical parts of the code, you are safe to go with the default
|
||||
value.
|
||||
|
||||
\param count The size of the blocks of memory allocated.
|
||||
\param count The size of the blocks of memory allocated.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn BList::BList(const BList& anotherList)
|
||||
\brief Copy constructor, copies a complete list into this one.
|
||||
\fn BList::BList(const BList& anotherList)
|
||||
\brief Copy constructor. Copy a complete list into this one.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn BList::~BList()
|
||||
\brief Destroy the list.
|
||||
\fn BList::~BList()
|
||||
\brief Destroy the list.
|
||||
|
||||
Please note that as BList does not assume ownership of the objects,
|
||||
only the list will be freed, not the objects that are held in it.
|
||||
Please note that as BList does not assume ownership of the objects,
|
||||
only the list will be freed, not the objects that are held in it.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn BList& BList::operator=(const BList &list)
|
||||
\brief Copy another list into this object.
|
||||
\fn BList& BList::operator=(const BList &list)
|
||||
\brief Copy another list into this object.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\name Adding and removing items
|
||||
\name Adding and removing items
|
||||
*/
|
||||
|
||||
//! @{
|
||||
|
||||
/*!
|
||||
\fn bool BList::AddItem(void *item, int32 index)
|
||||
\brief Add an item at a certain position.
|
||||
\fn bool BList::AddItem(void *item, int32 index)
|
||||
\brief Add an item at a certain position.
|
||||
|
||||
\param item The item to add.
|
||||
\param index The place in the list.
|
||||
\retval true The item was added.
|
||||
\retval false Item was not added. Either the index was negative or invalid,
|
||||
or resizing the list failed.
|
||||
\sa AddItem(void *item)
|
||||
\param item The item to add.
|
||||
\param index The place in the list.
|
||||
\retval true The item was added.
|
||||
\retval false Item was not added. Either the index was negative or invalid,
|
||||
or resizing the list failed.
|
||||
\see AddItem(void *item)
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn bool BList::AddItem(void *item)
|
||||
\brief Append an item to the list.
|
||||
\fn bool BList::AddItem(void *item)
|
||||
\brief Append an item to the list.
|
||||
|
||||
\param item The item to add.
|
||||
\retval true The item was appended.
|
||||
\retval true The item was added.
|
||||
\retval false Item was not appended, since resizing the list failed.
|
||||
\sa AddItem(void *item, int32 index)
|
||||
\param item The item to add.
|
||||
\retval true The item was appended.
|
||||
\retval false Item was not appended, since resizing the list failed.
|
||||
\see AddItem(void *item, int32 index)
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn bool BList::AddList(const BList *list, int32 index)
|
||||
\brief Add items from another list to this list at a certain position.
|
||||
\fn bool BList::AddList(const BList *list, int32 index)
|
||||
\brief Add items from another list to this list at a certain position.
|
||||
|
||||
Note that the \c list parameter is \c const, so the original list will not be altered.
|
||||
Note that the \a list parameter is \c const, so the original list will not be
|
||||
altered.
|
||||
|
||||
\param list The list to be added.
|
||||
\param index The position in the current list where the new item(s) should be put.
|
||||
\retval true The list was added.
|
||||
\retval false Failed to insert the list, due to the fact that resizing our list failed.
|
||||
\sa AddList(const BList *list)
|
||||
\param list The list to be added.
|
||||
\param index The position in the current list where the new item(s) should be
|
||||
put.
|
||||
\retval true The list was added.
|
||||
\retval false Failed to insert the list, due to the fact that resizing our
|
||||
list failed.
|
||||
\see AddList(const BList *list)
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn bool BList::AddList(const BList *list)
|
||||
\brief Append a list to this list.
|
||||
\fn bool BList::AddList(const BList *list)
|
||||
\brief Append a list to this list.
|
||||
|
||||
Note that the \c list parameter is \c const, so the original list will not be altered.
|
||||
Note that the \a list parameter is \c const, so the original list will not
|
||||
be altered.
|
||||
|
||||
\param list The list to be appended.
|
||||
\retval true The list was appended.
|
||||
\retval false Failed to append the list, due to the fact that resizing our list failed.
|
||||
\sa AddList(const BList *list, int32 index)
|
||||
\param list The list to be appended.
|
||||
\retval true The list was appended.
|
||||
\retval false Failed to append the list, due to the fact that resizing our
|
||||
list failed.
|
||||
\see AddList(const BList *list, int32 index)
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn bool BList::RemoveItem(void *item)
|
||||
\brief Remove an item from the list.
|
||||
\fn bool BList::RemoveItem(void *item)
|
||||
\brief Remove an item from the list.
|
||||
|
||||
\param item The item that should be removed.
|
||||
\retval true The item was found and removed.
|
||||
\retval false The item was not in this list and thus not removed.
|
||||
\sa RemoveItem(int32 index)
|
||||
\param item The item that should be removed.
|
||||
\retval true The item was found and removed.
|
||||
\retval false The item was not in this list and thus not removed.
|
||||
\see RemoveItem(int32 index)
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void * BList::RemoveItem(int32 index)
|
||||
\brief Remove the item at \c index from the list.
|
||||
\fn void * BList::RemoveItem(int32 index)
|
||||
\brief Remove the item at \a index from the list.
|
||||
|
||||
\param index The item that should be removed.
|
||||
\return The pointer to the item that was removed, or \c NULL in case the
|
||||
index was invalid.
|
||||
\sa RemoveItem(void *item)
|
||||
\param index The item that should be removed.
|
||||
\return The pointer to the item that was removed, or \c NULL in case the
|
||||
index was invalid.
|
||||
\see RemoveItem(void *item)
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn bool BList::RemoveItems(int32 index, int32 count)
|
||||
\brief Remove a number of items starting at a certain position.
|
||||
\fn bool BList::RemoveItems(int32 index, int32 count)
|
||||
\brief Remove a number of items starting at a certain position.
|
||||
|
||||
If the count parameter is larger than the number of items in the list,
|
||||
all the items from the offset to the end will be removed.
|
||||
If the count parameter is larger than the number of items in the list,
|
||||
all the items from the offset to the end will be removed.
|
||||
|
||||
\param index The offset in the list where removal should start.
|
||||
\param count The number of items to remove.
|
||||
\retval true Removal succeeded.
|
||||
\retval false Failed to remove the items because the index was invalid.
|
||||
\param index The offset in the list where removal should start.
|
||||
\param count The number of items to remove.
|
||||
\retval true Removal succeeded.
|
||||
\retval false Failed to remove the items because the index was invalid.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn bool BList::ReplaceItem(int32 index, void *newItem)
|
||||
\brief Replace a item with another one.
|
||||
\fn bool BList::ReplaceItem(int32 index, void *newItem)
|
||||
\brief Replace a item with another one.
|
||||
|
||||
\param index The offset in the list where to put the item.
|
||||
\param newItem The new item to put in the list.
|
||||
\retval true Item replaced.
|
||||
\retval false The index was invalid.
|
||||
\param index The offset in the list where to put the item.
|
||||
\param newItem The new item to put in the list.
|
||||
\retval true Item replaced.
|
||||
\retval false The index was invalid.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BList::MakeEmpty()
|
||||
\brief Clear all the items from the list.
|
||||
\fn void BList::MakeEmpty()
|
||||
\brief Clear all the items from the list.
|
||||
|
||||
Please note that this does not free the items.
|
||||
Please note that this does not free the items.
|
||||
*/
|
||||
|
||||
//! @}
|
||||
|
||||
/*!
|
||||
\name Reordering items
|
||||
\name Reordering items
|
||||
*/
|
||||
|
||||
//! @{
|
||||
|
||||
/*!
|
||||
\fn void BList::SortItems(int (*compareFunc)(const void *, const void *))
|
||||
\brief Sort the items with the use of a supplied comparison function.
|
||||
\fn void BList::SortItems(int (*compareFunc)(const void *, const void *))
|
||||
\brief Sort the items with the use of a supplied comparison function.
|
||||
|
||||
The function should take two \c const pointers as arguments and should return an
|
||||
integer.
|
||||
The function should take two \c const pointers as arguments and should return
|
||||
an integer.
|
||||
|
||||
For an example, see the Compare(const BString *, const BString *) function.
|
||||
For an example, see the Compare(const BString *, const BString *) function.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn bool BList::SwapItems(int32 indexA, int32 indexB)
|
||||
\brief Swap two items.
|
||||
\fn bool BList::SwapItems(int32 indexA, int32 indexB)
|
||||
\brief Swap two items.
|
||||
|
||||
\param indexA The first item.
|
||||
\param indexB The second item.
|
||||
\retval true Swap succeeded.
|
||||
\retval false Swap failed because one of the indexes were invalid.
|
||||
\param indexA The first item.
|
||||
\param indexB The second item.
|
||||
\retval true Swap succeeded.
|
||||
\retval false Swap failed because one of the indexes were invalid.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn bool BList::MoveItem(int32 fromIndex, int32 toIndex)
|
||||
\brief Move an item to a new place
|
||||
\fn bool BList::MoveItem(int32 fromIndex, int32 toIndex)
|
||||
\brief Move an item to a new place
|
||||
|
||||
This moves a list item from posititon a to position b, moving the appropriate
|
||||
block of list elements to make up for the move. For example, in the array:
|
||||
\verbatim
|
||||
This moves a list item from posititon a to position b, moving the appropriate
|
||||
block of list elements to make up for the move. For example, in the array:
|
||||
\verbatim
|
||||
A B C D E F G H I J
|
||||
\endverbatim
|
||||
Moveing 1(B)->6(G) would result in this:
|
||||
\verbatim
|
||||
\endverbatim
|
||||
|
||||
Moveing 1(B)->6(G) would result in this:
|
||||
\verbatim
|
||||
A C D E F G B H I J
|
||||
\endverbatim
|
||||
\endverbatim
|
||||
|
||||
\param fromIndex The original location.
|
||||
\param toIndex The new location.
|
||||
\retval true Move succeeded.
|
||||
\retval false Move failed since the indexes were invalid.
|
||||
\param fromIndex The original location.
|
||||
\param toIndex The new location.
|
||||
\retval true Move succeeded.
|
||||
\retval false Move failed since the indexes were invalid.
|
||||
*/
|
||||
|
||||
//! @}
|
||||
|
||||
/*!
|
||||
\name Retrieving items
|
||||
\name Retrieving items
|
||||
*/
|
||||
|
||||
//! @{
|
||||
|
||||
/*!
|
||||
\fn void *BList::ItemAt(int32 index) const
|
||||
\brief Get an item.
|
||||
\fn void *BList::ItemAt(int32 index) const
|
||||
\brief Get an item.
|
||||
|
||||
\param index The item to retrieve.
|
||||
\return A pointer to the item in that position, or \c NULL if the index is out of bounds.
|
||||
\sa ItemAtFast(int32 index) const
|
||||
\param index The item to retrieve.
|
||||
\return A pointer to the item in that position, or \c NULL if the index is
|
||||
out of bounds.
|
||||
\see ItemAtFast(int32 index) const
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void *BList::FirstItem() const
|
||||
\brief Get the first item.
|
||||
\return A pointer to the first item, or \c NULL if the list is empty.
|
||||
\fn void *BList::FirstItem() const
|
||||
\brief Get the first item.
|
||||
|
||||
\return A pointer to the first item, or \c NULL if the list is empty.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void *BList::ItemAtFast(int32 index) const
|
||||
\brief Get an item.
|
||||
\fn void *BList::ItemAtFast(int32 index) const
|
||||
\brief Get an item.
|
||||
|
||||
This method does not performs any boundary checks when it retrieves an item.
|
||||
Use this method in a performance critical area of your program where you are
|
||||
sure you won't get an invalid item.
|
||||
This method does not performs any boundary checks when it retrieves an item.
|
||||
Use this method in a performance critical area of your program where you are
|
||||
sure you won't get an invalid item.
|
||||
|
||||
\return A pointer to the item.
|
||||
\return A pointer to the item.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void *BList::LastItem() const
|
||||
\brief Get the last item.
|
||||
\return A pointer to the last item, or \c NULL if the list is empty.
|
||||
\fn void *BList::LastItem() const
|
||||
\brief Get the last item.
|
||||
\return A pointer to the last item, or \c NULL if the list is empty.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void *BList::Items() const
|
||||
\brief Return the internal list of objects.
|
||||
\fn void *BList::Items() const
|
||||
\brief Return the internal list of objects.
|
||||
|
||||
This method will return a pointer to the internal pointer list. This means you should be careful
|
||||
what you are doing, since you are directly working with the internals of the class.
|
||||
This method will return a pointer to the internal pointer list. This means
|
||||
you should be careful what you are doing, since you are directly working
|
||||
with the internals of the class.
|
||||
|
||||
It is definately not a good idea to make any changes to the list, since it will mess up
|
||||
the internal consistency.
|
||||
It is definately not a good idea to make any changes to the list, since it
|
||||
will mess up the internal consistency.
|
||||
|
||||
\warning If there is anything you want for which you need the list of objects, please
|
||||
realize that that probably means that what you want to do is a bad idea to begin with.
|
||||
Avoid this method. The list of objects doesn't belong to you. Check if DoForEach() can
|
||||
help you.
|
||||
\return The internal list of pointers.
|
||||
\warning If there is anything you want for which you need the list of
|
||||
objects, please realize that that probably means that what you want to do
|
||||
is a bad idea to begin with. Avoid this method. The list of objects doesn't
|
||||
belong to you. Check if DoForEach() can help you.
|
||||
\return The internal list of pointers.
|
||||
*/
|
||||
|
||||
//! @}
|
||||
|
||||
/*!
|
||||
\name Querying for items
|
||||
\name Querying for items
|
||||
*/
|
||||
|
||||
//! @{
|
||||
|
||||
/*!
|
||||
\fn bool BList::HasItem(void *item) const
|
||||
\brief Check if an item is in the list.
|
||||
\fn bool BList::HasItem(void *item) const
|
||||
\brief Check if an item is in the list.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn int32 BList::IndexOf(void *item) const
|
||||
\brief Get the index of an item.
|
||||
\fn int32 BList::IndexOf(void *item) const
|
||||
\brief Get the index of an item.
|
||||
|
||||
\return The index of the item, or -1 when the item is not in the list.
|
||||
\return The index of the item, or -1 when the item is not in the list.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn int32 BList::CountItems() const
|
||||
\brief Get the number of items in the list.
|
||||
\fn int32 BList::CountItems() const
|
||||
\brief Get the number of items in the list.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn bool BList::IsEmpty() const
|
||||
\brief Check if there are items in the list.
|
||||
\fn bool BList::IsEmpty() const
|
||||
\brief Check if there are items in the list.
|
||||
*/
|
||||
|
||||
//! @}
|
||||
|
||||
/*!
|
||||
\name Iterating over the list
|
||||
\name Iterating over the list
|
||||
*/
|
||||
|
||||
//! @{
|
||||
|
||||
/*!
|
||||
\fn void BList::DoForEach(bool (*func)(void* item))
|
||||
\brief Perform an action on every item in the list.
|
||||
\fn void BList::DoForEach(bool (*func)(void* item))
|
||||
\brief Perform an action on every item in the list.
|
||||
|
||||
If one of the actions on the items fails, meaning that the \c func function
|
||||
returned \c false, then the processing of the list will be stopped.
|
||||
If one of the actions on the items fails, meaning that the \a func function
|
||||
returned \c false, then the processing of the list will be stopped.
|
||||
|
||||
\param func A function that takes a \c void * argument and returns a boolean.
|
||||
\param func A function that takes a \c void * argument and returns a boolean.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void BList::DoForEach(bool (*func)(void* item, void* arg2), void *arg2)
|
||||
\brief Perform an action on every item in the list with an argument.
|
||||
\fn void BList::DoForEach(bool (*func)(void* item, void* arg2), void *arg2)
|
||||
\brief Perform an action on every item in the list with an argument.
|
||||
|
||||
If one of the actions on the items fails, meaning that the \c func function
|
||||
returned \c false, then the processing of the list will be stopped.
|
||||
If one of the actions on the items fails, meaning that the \a func function
|
||||
returned \c false, then the processing of the list will be stopped.
|
||||
|
||||
\param func A function with the first \c void * argument being the item,
|
||||
and the second \c void * being the argument that you supply. It should
|
||||
return a boolean value on whether it succeeded or not.
|
||||
\param arg2 An argument to supply to \c func.
|
||||
\param func A function with the first \c void * argument being the item,
|
||||
and the second \c void * being the argument that you supply. It should
|
||||
return a boolean value on whether it succeeded or not.
|
||||
\param arg2 An argument to supply to \a func.
|
||||
*/
|
||||
|
||||
//! @}
|
||||
|
||||
Reference in New Issue
Block a user