Difference between revisions of "DataPacks (AMX Mod X Scripting)"

From AlliedModders Wiki
Jump to: navigation, search
m
(Fixed typos)
 
Line 50: Line 50:
 
: Packs a cell value into a datapack.
 
: Packs a cell value into a datapack.
  
:{{alert|success|Example:|{{tt|WritePackString(pack, 42);|opt=nobg}}|opt=full-border}}
+
:{{alert|success|Example:|{{tt|WritePackCell(pack, 42);|opt=nobg}}|opt=full-border}}
  
 
{{margin|35px 0 15px 0|{{tt|WritePackFloat({{color|green|DataPack}}:{{h:title||pack}}, {{color|green|Float}}:{{h:title||val}})|opt=large}}}}
 
{{margin|35px 0 15px 0|{{tt|WritePackFloat({{color|green|DataPack}}:{{h:title||pack}}, {{color|green|Float}}:{{h:title||val}})|opt=large}}}}
 
: Packs a float value into a datapack.
 
: Packs a float value into a datapack.
  
:{{alert|success|Example:|{{tt|WritePackString(pack, 13.36);|opt=nobg}}|opt=full-border}}
+
:{{alert|success|Example:|{{tt|WritePackFloat(pack, 13.36);|opt=nobg}}|opt=full-border}}
  
 
{{margin|35px 0 15px 0|{{tt|WritePackString({{color|green|DataPack}}:{{h:title||pack}}, const {{h:title||str}}[])|opt=large}}}}
 
{{margin|35px 0 15px 0|{{tt|WritePackString({{color|green|DataPack}}:{{h:title||pack}}, const {{h:title||str}}[])|opt=large}}}}
Line 76: Line 76:
 
:{{alert|warning|Attention:|You need to reset the datapack before reading data.|opt=full-border}}
 
:{{alert|warning|Attention:|You need to reset the datapack before reading data.|opt=full-border}}
 
:{{alert|info|Return:|Cell value.|opt=full-border}}
 
:{{alert|info|Return:|Cell value.|opt=full-border}}
:{{alert|success|Example:|{{tt|new value <nowiki>=</nowiki> ReadPackString(pack);|opt=nobg}}|opt=full-border}}
+
:{{alert|success|Example:|{{tt|new value <nowiki>=</nowiki> ReadPackCell(pack);|opt=nobg}}|opt=full-border}}
  
 
{{margin|35px 0 15px 0|{{tt|{{color|green|Float}}:ReadPackFloat({{color|green|DataPack}}:{{h:title||pack}})|opt=large}}}}
 
{{margin|35px 0 15px 0|{{tt|{{color|green|Float}}:ReadPackFloat({{color|green|DataPack}}:{{h:title||pack}})|opt=large}}}}
Line 83: Line 83:
 
:{{alert|warning|Attention:|You need to reset the datapack before reading data.|opt=full-border}}
 
:{{alert|warning|Attention:|You need to reset the datapack before reading data.|opt=full-border}}
 
:{{alert|info|Return:|Float value.|opt=full-border}}
 
:{{alert|info|Return:|Float value.|opt=full-border}}
:{{alert|success|Example:|{{tt|new {{color|green|Float}}:value <nowiki>=</nowiki> ReadPackString(pack);|opt=nobg}}|opt=full-border}}
+
:{{alert|success|Example:|{{tt|new {{color|green|Float}}:value <nowiki>=</nowiki> ReadPackFloat(pack);|opt=nobg}}|opt=full-border}}
  
 
:{{margin|35px 0 15px 0|{{tt|ReadPackString({{color|green|DataPack}}:{{h:title||pack}}, {{h:title||buffer}}[], {{h:title||maxlen}})|opt=large}}}}
 
:{{margin|35px 0 15px 0|{{tt|ReadPackString({{color|green|DataPack}}:{{h:title||pack}}, {{h:title||buffer}}[], {{h:title||maxlen}})|opt=large}}}}

Latest revision as of 09:43, 18 June 2017

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:WritePackCell(pack, 42);
WritePackFloat(DataPack:pack, Float:val)
Packs a float value into a datapack.
Example:WritePackFloat(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 = ReadPackCell(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 = ReadPackFloat(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);
}