LumpReadString: Difference between revisions

From Zandronum Wiki
(Update specifications on failure)
Tag: Source edit
(Add example)
 
Line 8: Line 8:


===Parameters===
===Parameters===
* ''lump'': The lump index as returned from <tt>[[LumpOpen]]</tt>.
* ''lump'': The lump index as returned from [[LumpOpen]].
* ''pos'': The byte position in the lump to start reading the string from.
*''pos'': The byte position in the lump to start reading the string from.
* ''length'': The maximum number of characters to read.
*''length'': The maximum number of characters to read.


===Return value===
===Return value===
Line 17: Line 17:
Note the string returned might have a shorter length than what is specified by the ''length'' parameter, should the end of the file be reached.
Note the string returned might have a shorter length than what is specified by the ''length'' parameter, should the end of the file be reached.


The function returns an empty string when called on a lump that was not opened with <tt>[[LumpOpen]]</tt>, alongside a console message.
The function returns an empty string when called on a lump that was not opened with [[LumpOpen]], alongside a console message.


==Examples==
==Examples==
{{noexamples}}
<syntaxhighlight lang="js" line="1">
// This script opens all lumps with the name "MYLUMP" and reads the first 10 characters, starting at position zero.
// "MYLUMP" is not a real lump, and you should replace it with a lump that does exist.
// `CLIENTSIDE` is optional.
Script 1 OPEN CLIENTSIDE
{
int startIndex = -1;
while(true)
{
startIndex = LumpOpen("MYLUMP", startIndex + 1);
 
// The next lump was not found.
if (startIndex == -1) {
break;
}
// Read the first 10 characters that exists in the lump at position zero.
int value = LumpReadString(startIndex, 0, 10);
Log(s:"The string that was read is ", s:value, s:".");
 
// Make sure to close the lump again to free the handle.
LumpClose(startIndex);
}
}
</syntaxhighlight>
 
==See also==
*[[LumpOpen]]
*[[LumpRead]]
*[[LumpReadArray]]
*[[LumpGetInfo]]
*[[LumpClose]]


[[Category:ACS functions]]
[[Category:ACS functions]]

Latest revision as of 08:46, 4 January 2024

This article documents a Zandronum-specific ACS feature which may not be supported by ZDoom and its other child ports.
This article documents an ACS function which is only available in development builds of Zandronum 3.2 and newer.

str LumpReadString (int lump, int pos [, int length]) (development version 3.2-alpha and above only)

Usage

Reads a string from a lump, stopping upon encountering a null terminator or the end of the lump.

Parameters

  • lump: The lump index as returned from LumpOpen.
  • pos: The byte position in the lump to start reading the string from.
  • length: The maximum number of characters to read.

Return value

Returns the string that was read.

Note the string returned might have a shorter length than what is specified by the length parameter, should the end of the file be reached.

The function returns an empty string when called on a lump that was not opened with LumpOpen, alongside a console message.

Examples

// This script opens all lumps with the name "MYLUMP" and reads the first 10 characters, starting at position zero.
// "MYLUMP" is not a real lump, and you should replace it with a lump that does exist.
// `CLIENTSIDE` is optional.
Script 1 OPEN CLIENTSIDE
{
	int startIndex = -1;
	
	while(true)
	{
		startIndex = LumpOpen("MYLUMP", startIndex + 1);

		// The next lump was not found.
		if (startIndex == -1) {
			break;
		}
		
		// Read the first 10 characters that exists in the lump at position zero.
		int value = LumpReadString(startIndex, 0, 10);
		Log(s:"The string that was read is ", s:value, s:".");

		// Make sure to close the lump again to free the handle.
		LumpClose(startIndex);
	}
}

See also