# Ogre::MemoryDataStream Class Reference

Common subclass of DataStream for handling data from chunks of memory. More...

`#include <OgreDataStream.h>`

Inheritance diagram for Ogre::MemoryDataStream:

[legend]

List of all members.

## Public Member Functions

| MemoryDataStream (void *pMem, size_t size, bool freeOnClose=false)
| Wrap an existing memory chunk in a stream.
| MemoryDataStream (const String &name, void *pMem, size_t size, bool freeOnClose=false)
| Wrap an existing memory chunk in a named stream.
| MemoryDataStream (DataStream &sourceStream, bool freeOnClose=true)
| Create a stream which pre-buffers the contents of another stream.
| MemoryDataStream (DataStreamPtr &sourceStream, bool freeOnClose=true)
| Create a stream which pre-buffers the contents of another stream.
| MemoryDataStream (const String &name, DataStream &sourceStream, bool freeOnClose=true)
| Create a named stream which pre-buffers the contents of another stream.
| MemoryDataStream (const String &name, const DataStreamPtr &sourceStream, bool freeOnClose=true)
| Create a named stream which pre-buffers the contents of another stream.
| MemoryDataStream (size_t size, bool freeOnClose=true)
| Create a stream with a brand new empty memory chunk.
| MemoryDataStream (const String &name, size_t size, bool freeOnClose=true)
| Create a named stream with a brand new empty memory chunk.
| ~MemoryDataStream ()
uchar * | getPtr (void)
| Get a pointer to the start of the memory block this stream holds.
uchar * | getCurrentPtr (void)
| Get a pointer to the current position in the memory block this stream holds.
size_t | read (void *buf, size_t count)

Read the requisite number of bytes from the stream, stopping at the end of the file.

Parameters:

  | buf | Reference to a buffer pointer
  | count | Number of bytes to read

Returns:
  The number of bytes read

size_t | readLine (char *buf, size_t maxCount, const String &delim="\n")

Get a single line from the stream.

Remarks:
  The delimiter character is not included in the data returned, and it is skipped over so the next read will occur after it. The buffer contents will include a terminating character.

Note:
  If you used this function, you must open the stream in binary mode, otherwise, it'll produce unexpected results.

Parameters:

  | buf | Reference to a buffer pointer
  | maxCount | The maximum length of data to be read, excluding the terminating character
  | delim | The delimiter to stop at

Returns:
  The number of bytes read, excluding the terminating character

size_t | skipLine (const String &delim="\n")

Skip a single line from the stream.

Note:
  If you used this function, you must open the stream in binary mode, otherwise, it'll produce unexpected results.

Parameters:

  | delim | The delimiter(s) to stop at

Returns:
  The number of bytes skipped

void | skip (long count)
| Skip a defined number of bytes. This can also be a negative value, in which case the file pointer rewinds a defined number of bytes.
void | seek (size_t pos)
| Repositions the read point to a specified byte.
size_t | tell (void) const
| Returns the current byte offset from beginning.
bool | eof (void) const
| Returns true if the stream has reached the end.
void | close (void)
| Close the stream; this makes further operations invalid.
void | setFreeOnClose (bool free)
| Sets whether or not to free the encapsulated memory on close.
const String & | getName (void)
| Returns the name of the stream, if it has one.
template<typename T>
DataStream & | operator>> (T &val)
virtual String | getLine (bool trimAfter=true)
| Returns a String containing the next line of data, optionally trimmed for whitespace.
virtual String | getAsString (void)
| Returns a String containing the entire stream.
size_t | size (void) const
| Returns the total size of the data to be read from the stream, or 0 if this is indeterminate for this stream.
void * | operator new (size_t sz, const char *file, int line, const char *func)
| operator new, with debug line info
void * | operator new (size_t sz)
void * | operator new (size_t sz, void *ptr)
| placement operator new
void * | operator new[] (size_t sz, const char *file, int line, const char *func)
| array operator new, with debug line info
void * | operator new[] (size_t sz)
void | operator delete (void *ptr)
void | operator delete (void *ptr, void *)
void | operator delete (void *ptr, const char *, int, const char *)
void | operator delete[] (void *ptr)
void | operator delete[] (void *ptr, const char *, int, const char *)

## Protected Attributes

uchar * | mData
| Pointer to the start of the data area.
uchar * | mPos
| Pointer to the current position in the memory.
uchar * | mEnd
| Pointer to the end of the memory.
bool | mFreeOnClose
| Do we delete the memory on close.
String | mName
| The name (e.g. resource name) that can be used to identify the source fot his data (optional).
size_t | mSize
| Size of the data in the stream (may be 0 if size cannot be determined).

## Detailed Description

Common subclass of DataStream for handling data from chunks of memory.

Definition at line 169 of file OgreDataStream.h.

## Constructor & Destructor Documentation

Ogre::MemoryDataStream::MemoryDataStream | ( | void * | pMem,
|  | size_t | size,
|  | bool | freeOnClose = `false` |
| ) |  |  |

Wrap an existing memory chunk in a stream.

Parameters:

  | pMem | Pointer to the existing memory
  | size | The size of the memory chunk in bytes
  | freeOnClose | If true, the memory associated will be destroyed when the stream is destroyed. Note: it's important that if you set this option to true, that you allocated the memory using OGRE_ALLOC_T with a category of MEMCATEGORY_GENERAL ensure the freeing of memory matches up.

Ogre::MemoryDataStream::MemoryDataStream | ( | const String & | name,
|  | void * | pMem,
|  | size_t | size,
|  | bool | freeOnClose = `false` |
| ) |  |  |

Wrap an existing memory chunk in a named stream.

Parameters:

  | name | The name to give the stream
  | pMem | Pointer to the existing memory
  | size | The size of the memory chunk in bytes
  | freeOnClose | If true, the memory associated will be destroyed when the stream is destroyed. Note: it's important that if you set this option to true, that you allocated the memory using OGRE_ALLOC_T with a category of MEMCATEGORY_GENERAL ensure the freeing of memory matches up.

Ogre::MemoryDataStream::MemoryDataStream | ( | DataStream & | sourceStream,
|  | bool | freeOnClose = `true` |
| ) |  |  |

Create a stream which pre-buffers the contents of another stream.

Remarks:
  This constructor can be used to intentionally read in the entire contents of another stream, copying them to the internal buffer and thus making them available in memory as a single unit.

Parameters:

  | sourceStream | Another DataStream which will provide the source of data
  | freeOnClose | If true, the memory associated will be destroyed when the stream is destroyed.

Ogre::MemoryDataStream::MemoryDataStream | ( | DataStreamPtr & | sourceStream,
|  | bool | freeOnClose = `true` |
| ) |  |  |

Create a stream which pre-buffers the contents of another stream.

Remarks:
  This constructor can be used to intentionally read in the entire contents of another stream, copying them to the internal buffer and thus making them available in memory as a single unit.

Parameters:

  | sourceStream | Weak reference to another DataStream which will provide the source of data
  | freeOnClose | If true, the memory associated will be destroyed when the stream is destroyed.

Ogre::MemoryDataStream::MemoryDataStream | ( | const String & | name,
|  | DataStream & | sourceStream,
|  | bool | freeOnClose = `true` |
| ) |  |  |

Create a named stream which pre-buffers the contents of another stream.

Remarks:
  This constructor can be used to intentionally read in the entire contents of another stream, copying them to the internal buffer and thus making them available in memory as a single unit.

Parameters:

  | name | The name to give the stream
  | sourceStream | Another DataStream which will provide the source of data
  | freeOnClose | If true, the memory associated will be destroyed when the stream is destroyed.

Ogre::MemoryDataStream::MemoryDataStream | ( | const String & | name,
|  | const DataStreamPtr & | sourceStream,
|  | bool | freeOnClose = `true` |
| ) |  |  |

Create a named stream which pre-buffers the contents of another stream.

Remarks:
  This constructor can be used to intentionally read in the entire contents of another stream, copying them to the internal buffer and thus making them available in memory as a single unit.

Parameters:

  | name | The name to give the stream
  | sourceStream | Another DataStream which will provide the source of data
  | freeOnClose | If true, the memory associated will be destroyed when the stream is destroyed.

Ogre::MemoryDataStream::MemoryDataStream | ( | size_t | size,
|  | bool | freeOnClose = `true` |
| ) |  |  |

Create a stream with a brand new empty memory chunk.

Parameters:

  | size | The size of the memory chunk to create in bytes
  | freeOnClose | If true, the memory associated will be destroyed when the stream is destroyed.

Ogre::MemoryDataStream::MemoryDataStream | ( | const String & | name,
|  | size_t | size,
|  | bool | freeOnClose = `true` |
| ) |  |  |

Create a named stream with a brand new empty memory chunk.

Parameters:

  | name | The name to give the stream
  | size | The size of the memory chunk to create in bytes
  | freeOnClose | If true, the memory associated will be destroyed when the stream is destroyed.

Ogre::MemoryDataStream::~MemoryDataStream | ( |  | ) |

## Member Function Documentation

uchar* Ogre::MemoryDataStream::getPtr | ( | void |  | ) |

Get a pointer to the start of the memory block this stream holds.

Definition at line 280 of file OgreDataStream.h.

uchar* Ogre::MemoryDataStream::getCurrentPtr | ( | void |  | ) |

Get a pointer to the current position in the memory block this stream holds.

Definition at line 283 of file OgreDataStream.h.

size_t Ogre::MemoryDataStream::read | ( | void * | buf,
|  | size_t | count |
| ) |  |  | `[virtual]`

Read the requisite number of bytes from the stream, stopping at the end of the file.

Parameters:

  | buf | Reference to a buffer pointer
  | count | Number of bytes to read

Returns:
  The number of bytes read

Implements Ogre::DataStream.

size_t Ogre::MemoryDataStream::readLine | ( | char * | buf,
|  | size_t | maxCount,
|  | const String & | delim = `"\n"` |
| ) |  |  | `[virtual]`

Get a single line from the stream.

Remarks:
  The delimiter character is not included in the data returned, and it is skipped over so the next read will occur after it. The buffer contents will include a terminating character.

Note:
  If you used this function, you must open the stream in binary mode, otherwise, it'll produce unexpected results.

Parameters:

  | buf | Reference to a buffer pointer
  | maxCount | The maximum length of data to be read, excluding the terminating character
  | delim | The delimiter to stop at

Returns:
  The number of bytes read, excluding the terminating character

Reimplemented from Ogre::DataStream.

size_t Ogre::MemoryDataStream::skipLine | ( | const String & | delim = `"\n"` | ) | `[virtual]`

Skip a single line from the stream.

Note:
  If you used this function, you must open the stream in binary mode, otherwise, it'll produce unexpected results.

Parameters:

  | delim | The delimiter(s) to stop at

Returns:
  The number of bytes skipped

Reimplemented from Ogre::DataStream.

void Ogre::MemoryDataStream::skip | ( | long | count | ) | `[virtual]`

Skip a defined number of bytes.

This can also be a negative value, in which case the file pointer rewinds a defined number of bytes.

Implements Ogre::DataStream.

void Ogre::MemoryDataStream::seek | ( | size_t | pos | ) | `[virtual]`

Repositions the read point to a specified byte.

Implements Ogre::DataStream.

size_t Ogre::MemoryDataStream::tell | ( | void |  | ) | const`[virtual]`

Returns the current byte offset from beginning.

Implements Ogre::DataStream.

bool Ogre::MemoryDataStream::eof | ( | void |  | ) | const`[virtual]`

Returns true if the stream has reached the end.

Implements Ogre::DataStream.

void Ogre::MemoryDataStream::close | ( | void |  | ) | `[virtual]`

Close the stream; this makes further operations invalid.

Implements Ogre::DataStream.

void Ogre::MemoryDataStream::setFreeOnClose | ( | bool | free | ) |

Sets whether or not to free the encapsulated memory on close.

Definition at line 317 of file OgreDataStream.h.

const String& Ogre::DataStream::getName | ( | void |  | ) | `[inherited]`

Returns the name of the stream, if it has one.

Definition at line 72 of file OgreDataStream.h.

template<typename T>

DataStream& Ogre::DataStream::operator>> | ( | T & | val | ) | `[inherited]`

virtual String Ogre::DataStream::getLine | ( | bool | trimAfter = `true` | ) | `[virtual, inherited]`

Returns a String containing the next line of data, optionally trimmed for whitespace.

Remarks:
  This is a convenience method for text streams only, allowing you to retrieve a String object containing the next line of data. The data is read up to the next newline character and the result trimmed if required.

Note:
  If you used this function, you must open the stream in binary mode, otherwise, it'll produce unexpected results.

Parameters:

  | trimAfter | If true, the line is trimmed for whitespace (as in String.trim(true,true))

virtual String Ogre::DataStream::getAsString | ( | void |  | ) | `[virtual, inherited]`

Returns a String containing the entire stream.

Remarks:
  This is a convenience method for text streams only, allowing you to retrieve a String object containing all the data in the stream.

size_t Ogre::DataStream::size | ( | void |  | ) | const`[inherited]`

Returns the total size of the data to be read from the stream, or 0 if this is indeterminate for this stream.

Definition at line 149 of file OgreDataStream.h.

template<class Alloc>

void* Ogre::AllocatedObject< Alloc >::operator new | ( | size_t | sz,
|  | const char * | file,
|  | int | line,
|  | const char * | func |
| ) |  |  | `[inherited]`

operator new, with debug line info

Definition at line 62 of file OgreMemoryAllocatedObject.h.

template<class Alloc>

void* Ogre::AllocatedObject< Alloc >::operator new | ( | size_t | sz | ) | `[inherited]`

Definition at line 67 of file OgreMemoryAllocatedObject.h.

template<class Alloc>

void* Ogre::AllocatedObject< Alloc >::operator new | ( | size_t | sz,
|  | void * | ptr |
| ) |  |  | `[inherited]`

placement operator new

Definition at line 73 of file OgreMemoryAllocatedObject.h.

template<class Alloc>

void* Ogre::AllocatedObject< Alloc >::operator new[] | ( | size_t | sz,
|  | const char * | file,
|  | int | line,
|  | const char * | func |
| ) |  |  | `[inherited]`

array operator new, with debug line info

Definition at line 79 of file OgreMemoryAllocatedObject.h.

template<class Alloc>

void* Ogre::AllocatedObject< Alloc >::operator new[] | ( | size_t | sz | ) | `[inherited]`

Definition at line 84 of file OgreMemoryAllocatedObject.h.

template<class Alloc>

void Ogre::AllocatedObject< Alloc >::operator delete | ( | void * | ptr | ) | `[inherited]`

Definition at line 89 of file OgreMemoryAllocatedObject.h.

template<class Alloc>

void Ogre::AllocatedObject< Alloc >::operator delete | ( | void * | ptr,
|  | void * |  |
| ) |  |  | `[inherited]`

Definition at line 95 of file OgreMemoryAllocatedObject.h.

template<class Alloc>

void Ogre::AllocatedObject< Alloc >::operator delete | ( | void * | ptr,
|  | const char * | ,
|  | int | ,
|  | const char * |  |
| ) |  |  | `[inherited]`

Definition at line 101 of file OgreMemoryAllocatedObject.h.

template<class Alloc>

void Ogre::AllocatedObject< Alloc >::operator delete[] | ( | void * | ptr | ) | `[inherited]`

Definition at line 106 of file OgreMemoryAllocatedObject.h.

template<class Alloc>

void Ogre::AllocatedObject< Alloc >::operator delete[] | ( | void * | ptr,
|  | const char * | ,
|  | int | ,
|  | const char * |  |
| ) |  |  | `[inherited]`

Definition at line 112 of file OgreMemoryAllocatedObject.h.

## Member Data Documentation

uchar* Ogre::MemoryDataStream::mData `[protected]`

Pointer to the start of the data area.

Definition at line 173 of file OgreDataStream.h.

uchar* Ogre::MemoryDataStream::mPos `[protected]`

Pointer to the current position in the memory.

Definition at line 175 of file OgreDataStream.h.

uchar* Ogre::MemoryDataStream::mEnd `[protected]`

Pointer to the end of the memory.

Definition at line 177 of file OgreDataStream.h.

bool Ogre::MemoryDataStream::mFreeOnClose `[protected]`

Do we delete the memory on close.

Definition at line 179 of file OgreDataStream.h.

String Ogre::DataStream::mName `[protected, inherited]`

The name (e.g. resource name) that can be used to identify the source fot his data (optional).

Definition at line 62 of file OgreDataStream.h.

size_t Ogre::DataStream::mSize `[protected, inherited]`

Size of the data in the stream (may be 0 if size cannot be determined).

Definition at line 64 of file OgreDataStream.h.

The documentation for this class was generated from the following file:

- OgreDataStream.h

Copyright © 2008 Torus Knot Software Ltd
This work is licensed under a Creative Commons Attribution-ShareAlike 2.5 License.
Last modified Sun Jul 26 11:33:05 2009