Strings management functions. More...

Functions
string_t	PR_CatStrings (progs_t pr, const char a, const char *b)
	Make a temporary progs string that is the concatenation of two C strings. More...

void	PR_ClearReturnStrings (progs_t *pr)
	Clear all of the return string slots. More...

void	PR_FreeString (progs_t *pr, string_t str)
	Destroy a mutable, dynamic or temporary string. More...

void	PR_FreeTempStrings (progs_t *pr)
	Free all the temporary strings allocated in the current stack frame. More...

struct dstring_s *	PR_GetMutableString (progs_t *pr, string_t num)
	Retrieve the dstring_t associated with a mutable string. More...

const char *	PR_GetString (progs_t *pr, string_t num)
	Convert a string index to a C string. More...

int	PR_LoadStrings (progs_t *pr)
	Initialize the string tables using the strings supplied by the progs. More...

void	PR_MakeTempString (progs_t *pr, string_t str)
	Convert a mutable string to a temporary string. More...

string_t	PR_NewMutableString (progs_t *pr)
	Create a new mutable string. More...

string_t	PR_SetDynamicString (progs_t pr, const char s)
	Make a dynamic progs string from the given C string. More...

string_t	PR_SetReturnString (progs_t pr, const char s)
	Make a temporary progs string that will survive across function returns. More...

string_t	PR_SetString (progs_t pr, const char s)
	Make a permanent progs string from the given C string. More...

string_t	PR_SetTempString (progs_t pr, const char s)
	Make a temporary progs string that will be freed when the current progs stack frame is exited. More...

void	PR_Sprintf (progs_t pr, struct dstring_s result, const char name, const char format, int count, pr_type_t **args)
	Formatted printing similar to C's vsprintf, but using QC types. More...

qboolean	PR_StringValid (progs_t *pr, string_t num)
	Check the validity of a string index. More...

Detailed Description

Strings management functions.

All strings accessable by the VM are stored within the VM address space. These functions provide facilities to set permanent, dynamic and temporary strings, as well as mutable strings using dstrings.

Permanent strings are either supplied by the progs (+ve string index) or set by the main program using PR_SetString(). Permanent strings can never be altered and will exist until the next progs load.

Dynamic strings can be freed at any time, but not altered.

Temporary strings are always set by the main program using PR_SetTempString() or PR_CatStrings(). They will be freed when the current progs stack frame is cleared. Use PR_PushFrame() and PR_PopFrame() around the calls to PR_SetTempString() and PR_ExecuteProgram() when using strings as parameters to a progs function.

Mutable strings are dstrings (dstring_t) mapped into the VM address space. They can be created, altered, and destroyed at any time by the main program (or the progs code via an appropriate builtin function).

Function Documentation

string_t PR_CatStrings	(	progs_t *	pr,
		const char *	a,
		const char *	b
	)

Make a temporary progs string that is the concatenation of two C strings.

Parameters

pr	pointer to progs_t VM struct
a	C string
b	C string

Returns: string index of the progs string that represents the concatenation of strings a and b

void PR_ClearReturnStrings ( progs_t * pr )

Clear all of the return string slots.

Called at progs load.

Parameters

pr	pointer to progs_t VM struct

void PR_FreeString	(	progs_t *	pr,
		string_t	str
	)

Destroy a mutable, dynamic or temporary string.

Parameters

pr	pointer to progs_t VM struct
str	string index of the string to be destroyed

void PR_FreeTempStrings ( progs_t * pr )

Free all the temporary strings allocated in the current stack frame.

Parameters

pr	pointer to progs_t VM struct

struct dstring_s* PR_GetMutableString	(	progs_t *	pr,
		string_t	num
	)

Retrieve the dstring_t associated with a mutable string.

Parameters

pr	pointer to progs_t VM struct
num	string index of the mutable string

Returns: the dstring implementing the mutable string

const char* PR_GetString	(	progs_t *	pr,
		string_t	num
	)

Convert a string index to a C string.

Parameters

pr	pointer to progs_t VM struct
num	string index to be converted

Returns: C pointer to the string.

int PR_LoadStrings ( progs_t * pr )

Initialize the string tables using the strings supplied by the progs.

Called automatically during progs load.

Parameters

pr	pointer to progs_t VM struct

Returns: true for success, false for failure

void PR_MakeTempString	(	progs_t *	pr,
		string_t	str
	)

Convert a mutable string to a temporary string.

Parameters

pr	pointer to progs_t VM struct
str	string index of the mutable string to be converted

string_t PR_NewMutableString ( progs_t * pr )

Create a new mutable string.

Parameters

pr	pointer to progs_t VM struct

Returns: string index of the newly created mutable string

string_t PR_SetDynamicString	(	progs_t *	pr,
		const char *	s
	)

Make a dynamic progs string from the given C string.

Will not create a duplicate permanent string (temporary, dynamic and mutable strings are not checked).

Parameters

pr	pointer to progs_t VM struct
s	C string to be made into a permanent progs string

Returns: string index of the progs string

string_t PR_SetReturnString	(	progs_t *	pr,
		const char *	s
	)

Make a temporary progs string that will survive across function returns.

Will not duplicate a permanent string. If a new progs string is created, it will be freed after PR_RS_SLOTS calls to this function. ie, up to PR_RS_SLOTS return strings can exist at a time.

Parameters

pr	pointer to progs_t VM struct
s	C string to be returned to the progs code

Returns: string index of the progs string

string_t PR_SetString	(	progs_t *	pr,
		const char *	s
	)

Make a permanent progs string from the given C string.

Will not create a duplicate permanent string (temporary and mutable strings are not checked).

Parameters

pr	pointer to progs_t VM struct
s	C string to be made into a permanent progs string

Returns: string index of the progs string

string_t PR_SetTempString	(	progs_t *	pr,
		const char *	s
	)

Make a temporary progs string that will be freed when the current progs stack frame is exited.

Will not duplicate a permantent string.

Parameters

pr	pointer to progs_t VM struct
s	C string

Returns: string index of the progs string

Examples:: vm-exec.c.

void PR_Sprintf	(	progs_t *	pr,
		struct dstring_s *	result,
		const char *	name,
		const char *	format,
		int	count,
		pr_type_t **	args
	)

Formatted printing similar to C's vsprintf, but using QC types.

The format string is a string of characters (other than %) to be printed that includes optional format specifiers, one for each arg to be printed. A format specifier can be one of two forms:

"%%" print a single '%'
%[flags][field width][precision](conversion specifier) print a single arg of the type specified by the conversion specifier using the given format.

flags (optional)
- '#' print the value using an alternat form
- '0' the value should be zero padded
- '-' the value is to be left adjusted on the field bondary.
- ' ' A blank should be left before a positve number (or empty string) produced by a signed conversion.
- '+' A sign (+ or -) will always be placed before a number produced by a signed conversion.
field width (optional)
- a string of decimal digits with nonzero first digit.
precision (optional)
- a string consisting of '.' followed by 0 or more decimal digits.
conversion specifier (mandatory)
- '@' id Not yet implemented. Silently ignored.
- 'e' entity Prints the edict number of the given entity ("%i")
- 'i' integer Print a integer value. ("%i")
- 'f' float Print a float value. ("%f")
- 'g' float Print a float value. ("%f")
- 'p' void * Print a pointer value. ("%#x")
- 's' string Print a string value. ("%s")
- 'v' vector Print a vector value. ("'%g %g %g'")
- 'q' quaternion Print a quaternion value. ("'%g %g %g %g'")
- 'x' uinteger Print an unsigned integer value. ("%x")

For details, refer to the C documentation for printf.

Parameters

pr	pointer to progs_t VM struct
result	dstring to which printing is done
name	name to be reported in case of errors
format	the format string
count	number of args
args	array of pointers to the values to be printed

qboolean PR_StringValid	(	progs_t *	pr,
		string_t	num
	)

Check the validity of a string index.

Parameters

pr	pointer to progs_t VM struct
num	string index to be validated

Returns: true if the index is valid, false otherwise

Functions

Detailed Description

Function Documentation