Stream

---

The stream provides an interface to deal with binary and text data. The API below allows you to load, store data on disk, enables you to quickly compress stream (LZ) and allows you to manipulate the data stream as you see fit.

Find and replace functionalities are also available along with other convenient helper function to efficiently interact even with a large data stream. The interface below provides you the key functionalities of the stream available for Lua.

See Also

Script, Utility

Static Variables

---

Name	Description
size	Total size in bytes of the current Stream.
Declaration unsigned int size
cursor	Current location of the cursor within the Stream.
Declaration unsigned int cursor
data	Current data contained in the active Stream.
Declaration unsigned char *data
name	The filename of the Stream.
Declaration char *name

Functions

---

Name	Description
CompressLZ	Compress the current Stream data using LZ compression.
Declaration float CompressLZ( void ) Return Value The compression ratio. Note This function will add 8 bytes at the beginning of the Stream data which are used as a header. The header contain the compressed and uncompressed size.
DecompressLZ	Decompress an LZ data Stream.
Declaration bool DecompressLZ( void ) Return Value true on success; false if the header is invalid or an unknown compression level was used.
Store	Save the current data Stream to a binary file.
Declaration bool Store( const char *filename ) Parameters filename: Filename (either full or relative) where to store the data. Return Value true if the Stream have been saved without error; else return false.
StoreText	Save the current data Stream to a text file.
Declaration bool StoreText( const char *filename ) Parameters filename: Filename (either full or relative) where to store the data. Return Value true if the Stream have been saved without error; else return false.
SetData	Manually set Stream data.
Declaration void SetData( const char *data, unsigned int size ) Parameters data: To data to fill the Stream with. size: The size of the binary data in bytes; if the data is text simply pass 0 and the size will be evaluated automatically.
Load	Load an existing file from disk to the active Stream.
Declaration bool Load( const char *filename ) Parameters filename: Filepath (either full or relative) of the file to load. Return Value true is the operation succeed; false the file was not accessible.
Clear	Clear the current Stream and reset the size and data back to zero.
Declaration void Clear( void )
Reset	Clear and flush the internal Stream cache.
Declaration void Reset( void )
Clean	Cleanup the Stream; reset and clear the Stream and optionally flush the cache.
Declaration void Clean( bool flush_cache )
Reset	Clear and flush the internal Stream cache.
Declaration void Reset( void )
Alloc	Pre-allocate the active Stream.
Declaration void Alloc( unsigned int size ) Parameters size: Size in bytes of the memory to pre-allocate.
Write	Write data to the active Stream.
Declaration unsigned int Write( const char *data, unsigned int size ) Parameters data: Data to write. size: Size of the binary data; for text data simply leave to 0.
Append	Append data at the end of the Stream.
Declaration void Append( const char *data, unsigned int size ) Parameters data: Data to append. size: Size of the binary data; for text data simply leave to 0.
Insert	Write data to the active Stream.
Declaration bool Insert( const char *data, unsigned int size, unsigned int cursor ) Parameters data: Data to write. size: Size of the binary data; for text data simply leave to 0. cursor: A valid cursor position within the current Stream. Return Value false if the cursor provided is not between the Stream boundaries; else return true.
Replace	Find and replace a specific string within the Stream data.
Declaration unsigned int Replace( unsigned int cursor, const char *find, const char *replace, bool replace_all, bool case_sensitive ) Parameters cursor: Location where to start the find and replace operation. find: The string to find. replace: The string replace it with. replace_all: Determine wheter or not all occurences should be replaced of simply the first one found. case_sensitive: Specify if the operation should be case-sensitive or not. Return Value The amount of times the function successfully find and replace the string.
GetLineCount	Return the amount of lines contains in the Stream text data.
Declaration unsigned int GetLineCount( void ) Return Value The amount of line feed found in the text data.
Find	Find a specific string within the Stream text data.
Declaration int Find( unsigned int cursor, const char *find, bool case_sensitive ) Parameters cursor: Location where to start the find operation. find: The string to find. case_sensitive: Specify if the search should be case-sensitive or not. Return Value The character index where the string was found; else return -1.

Scripting

---

The Stream scripting interface is similar to the one used for Pose; contrarily to the other available API they require you to initialize and free the memory object. However, the rest of the API interactions with the scripting and plugins languages are standard to the rest of the NRG API.

Find below a quick example to learn how to use the Stream interface:

• Lua
• C/C++

-- Create a new Stream
local str = Stream.Init()
-- Load an existing text file.
if not str:Load("../../mytext.txt") then        
    print("The file could not be loaded." )
else
    -- Get the total line count.
    print("Line Count:" .. str:GetLineCount() )     
    -- Convert the bytes to a string.
    local w = {}        
    for i=1,table.getn(str.data) do 
        w[i] = string.char(str.data[i]) 
    end
    -- Print the string.
    print( table.concat(w) )        
    -- Compress the Stream.
    print("Compression Ratio:" .. string.format( "%.2f%%", str:CompressLZ() * 100.0 ) )     
    -- Save to compressed Stream on disk.
    if not str:Store( "../../mytext.lz" ) then      
        print("Cannot save compressed file.")
    else
        print("Saved...")
    end     
end
-- You are responsible to destroy the Stream to avoid leaks.
str = nil

// Create a new Stream
Stream str = StreamCreate();
// Load an existing text file.
if( !StreamLoad( &str, "C:/Users/rom/Desktop/mytext.txt" ) ) {  
    printf("The file could not be loaded\n" );
}
else {
    // Get the total line count.
    printf("Line Count:%d\n", StreamGetLineCount( &str ) );
    // Print the Stream as a string.
    printf("%s", ( char * )str.data );
    // Compress the Stream.
    float ratio = StreamCompressLZ( &str );         
    printf("Compression Ratio:%.2f%%\n", ratio * 100.0f );
    // Save to compressed Stream on disk.
    if( !StreamStore( &str,"C:/Users/rom/Desktop/mytext.lz" ) ) {
        printf("Cannot save compressed file.\n");   
    }
    else {
        printf("Saved...\n");
    }
}   
// You are responsible to destroy the Stream to avoid leaks.
StreamDestroy( &str );