DataPacks (AMX Mod X Scripting)

Language:	English

About

Datapacks provide a way to store and move around arbitrary amounts (and types) of data in AMX Mox X, available from datapack.inc.
Data is packed into a single cell value - the DataPack handle. This handle can be passed around more easily, can be returned by functions and can simulate advanced concepts like string consummation.

Usage

Creating & Disposing

DataPack:CreateDataPack()

Creates a new datapack.

Return:New datapack handle, which must be freed via DestroyDataPack.

Important:Plugins are responsible for freeing all datapack handles they acquire. Failing to free handles will result in the plugin and AMXX leaking memory.

Example:new const DataPack:handle = CreateDataPack();

DestroyDataPack(&DataPack:pack)

Destroys the datapack and frees its memory.

pack	Datapack handle to free.

Note:pack will be reset to 0.

Example:DestroyDataPack(pack);

Resetting

ResetPack(DataPack:pack, bool:clear = false)

Resets the datapack read/write position to the start.

clear

If true, clears the contained data.

Attention:You need to reset the datapack before reading data.

Example:ResetPack(pack);

Writing data

WritePackCell(DataPack:pack, any:cell)

Packs a cell value into a datapack.

Example:WritePackString(pack, 42);

WritePackFloat(DataPack:pack, Float:val)

Packs a float value into a datapack.

Example:WritePackString(pack, 13.36);

WritePackString(DataPack:pack, const str[])

Packs a string value into a datapack.

Return:Length of copied string.

Example:new const length = WritePackString(pack, "Hello world!");

Reading data

bool:IsPackEnded(DataPack:pack)

Returns if the datapack has reached its end and no more data can be read.

Return:True if datapack has reached the end, false otherwise.

Example:if (IsPackEnded(pack)) {}

any:ReadPackCell(DataPack:pack)

Reads a cell from a Datapack.

Attention:You need to reset the datapack before reading data.

Return:Cell value.

Example:new value = ReadPackString(pack);

Float:ReadPackFloat(DataPack:pack)

Reads a float from a Datapack.

Attention:You need to reset the datapack before reading data.

Return:Float value.

Example:new Float:value = ReadPackString(pack);

ReadPackString(DataPack:pack, buffer[], maxlen)

Reads a string from a Datapack.

Attention:You need to reset the datapack before reading data.

Return:Number of cells written to buffer.

Example:new buffer[32];
new const length = ReadPackString(pack, buffer, charsmax(buffer));

Managing position

DataPackPos:GetPackPosition(DataPack:pack)

Returns the datapack read/write position.

Return:Position in the datapack, only usable with calls to SetPackPosition.

Example:new const DataPackPos:position = GetPackPosition(pack);

SetPackPosition(DataPack:pack, DataPackPos:position)

Sets the datapack read/write position.

Attention:This should only ever be used with (known to be valid) positions returned by GetPackPosition. It is not possible for plugins to safely compute datapack positions.

Example:SetPackPosition(pack, position);

Example

foo()
{
    // Creating
    new const DataPack:pack = CreateDataPack();
 
    // Writing
    WritePackCell(pack, refCell);
    WritePackFloat(pack, refFloat);
    WritePackString(pack, refString);
 
    // Reset before reading
    ResetPack(pack);
    server_print("Datapack is readable: %s", !IsPackEnded(pack) ? "yes" : "no");
 
    // Reading
    new cellValue = ReadPackCell(pack);
    new Float:floatValue = ReadPackFloat(pack);
    new buffer[32];
    ReadPackString(pack, buffer, charsmax(buffer));
    server_print("cellValue = %d, floatValue = %f, buffer = %s", cellValue, floatValue, buffer)
    server_print("Datapack is no more readable: %s", IsPackEnded(pack) ? "yes" : "no");
 
    // Clear all data
    ResetPack(pack, .clear = true);
    server_print("Datapack is empty: %s", IsPackEnded(pack) ? "yes" : "no");
 
    // Disposing
    DestroyDataPack(pack);
}