Difference between revisions of "UTIL VarArgs"

From Valve Developer Community
Jump to: navigation, search
m
 
(9 intermediate revisions by 4 users not shown)
Line 1: Line 1:
This function will build a C-String similar to printf. It is server-side only!
+
{{DISPLAYTITLE:UTIL_VarArgs}}
 +
'''UTIL_VarArgs''' is a [http://en.wikipedia.org/wiki/Variadic_function Variadic function] [[UTIL]] provided to build a [[string|C-String]] similar to printf. ''UTIL_VarArgs'' is used by serverside code while ''VarArgs'' is its equivalent in the client project. The formatted result will be stored in a static buffer (1024 bytes, or 1kb) in size, and a [[pointer]] to its location will be returned. It is useful for quickly building a composite string for immediate usage, but due to its nature you may not save the pointer that is returned for later use. As soon this [[function]] is called another time, the latest result will be overwritten. Functions like [[strdup]] can be used to duplicate the output.
  
Example:
+
== Usage ==
<code>
+
<source lang=cpp>
 +
//-----------------------------------------------------------------------------
 +
// Purpose: Prints a message to console
 +
// Input  : format - See examples
 +
// Output : a char-array that is easily used in Msg, etc.
 +
//-----------------------------------------------------------------------------
 +
char *UTIL_VarArgs( char *format, ... )
 +
{
 +
va_list argptr;
 +
static char string[1024];
 +
 +
va_start (argptr, format);
 +
Q_vsnprintf(string, sizeof(string), format,argptr);
 +
va_end (argptr);
 +
 
 +
return string;
 +
}
 +
</source>
 +
 
 +
== Examples ==
 +
 
 +
<source lang=cpp>
 
int iCreepers = 3;
 
int iCreepers = 3;
char * pFortress = "My Awesome Fort.";
+
 
 +
char * pFortress = "My Awesome Fortress.";
 
char * pOutput = UTIL_VarArgs( "There are %i creepers outside of your %s.", iCreepers, pFortress );
 
char * pOutput = UTIL_VarArgs( "There are %i creepers outside of your %s.", iCreepers, pFortress );
Msg("%s", output);
 
  
// prints: There are 3 creepers outside of your My Awesome Fortress.
+
Msg("%s", pOutput );
</code>
+
 
 +
//Prints: There are 3 creepers outside of your My Awesome Fortress.
 +
</source>
 +
 
 +
<source lang=cpp>
 +
//This example uses a UTIL_VarArgs to prefix a string, and then execute a console command.
 +
void CPointDevShotCamera::DevShotThink_TakeShot( void )
 +
{
 +
// Take the screenshot
 +
CBasePlayer *pPlayer = UTIL_GetLocalPlayerOrListenServerHost();
 +
if ( !pPlayer )
 +
return;
 +
 
 +
engine->ClientCommand( pPlayer->edict(), UTIL_VarArgs( "devshots_screenshot \"%s\"", STRING(m_iszCameraName) ) );
 +
 
 +
// Now take the shot next frame
 +
SetThink( &CPointDevShotCamera::DevShotThink_PostShot );
 +
SetNextThink( gpGlobals->curtime + (DEVSHOT_INTERVAL - 1) );
 +
}
 +
</source>
 +
 
 +
<source lang=cpp>
 +
//This example gets the current map name, and appends it onto the end of a prefix string
 +
//It's used to find per-map files, such as custom soundscapes.
 +
const char *mapname = STRING( gpGlobals->mapname );
 +
const char *mapSoundscapeFilename = NULL;
 +
if ( mapname && *mapname )
 +
{
 +
mapSoundscapeFilename = UTIL_VarArgs( "scripts/soundscapes_%s.txt", mapname );
 +
}
 +
</source>
  
This is useful for quickly building a composite string.
+
<source lang=cpp>
 +
//This example just prints the player's current eye angles when called.
 +
CBasePlayer *pPlayer = UTIL_GetCommandClient();
 +
if (!pPlayer)
 +
    return;
 +
char *pOutput = UTIL_VarArgs( "Player X: %.2f, Y: %.2f, Z: %.2f\n", pPlayer->EyeAngles().x, pPlayer->EyeAngles().y, pPlayer->EyeAngles().z );
 +
Msg( "%s", pOutput );
 +
</source>
  
<code>
+
[[Category:Programming]]
char * pOutput = UTIL_VarArgs( "X:%f Y:%f Z:%f\n", vec.x, vec.y, vec.z );
+
[[Category:UTIL]]
</code>
 

Latest revision as of 00:28, 5 December 2011

UTIL_VarArgs is a Variadic function UTIL provided to build a C-String similar to printf. UTIL_VarArgs is used by serverside code while VarArgs is its equivalent in the client project. The formatted result will be stored in a static buffer (1024 bytes, or 1kb) in size, and a pointer to its location will be returned. It is useful for quickly building a composite string for immediate usage, but due to its nature you may not save the pointer that is returned for later use. As soon this function is called another time, the latest result will be overwritten. Functions like strdup can be used to duplicate the output.

Usage

//-----------------------------------------------------------------------------
// Purpose: Prints a message to console
// Input  : format - See examples
// Output : a char-array that is easily used in Msg, etc.
//-----------------------------------------------------------------------------
char *UTIL_VarArgs( char *format, ... )
{
	va_list		argptr;
	static char		string[1024];
	
	va_start (argptr, format);
	Q_vsnprintf(string, sizeof(string), format,argptr);
	va_end (argptr);

	return string;	
}

Examples

int iCreepers = 3;

char * pFortress = "My Awesome Fortress.";
char * pOutput = UTIL_VarArgs( "There are %i creepers outside of your %s.", iCreepers, pFortress );

Msg("%s", pOutput );

//Prints: There are 3 creepers outside of your My Awesome Fortress.
//This example uses a UTIL_VarArgs to prefix a string, and then execute a console command.
void CPointDevShotCamera::DevShotThink_TakeShot( void )
{
	// Take the screenshot
	CBasePlayer *pPlayer = UTIL_GetLocalPlayerOrListenServerHost();
	if ( !pPlayer )
		return;

	engine->ClientCommand( pPlayer->edict(), UTIL_VarArgs( "devshots_screenshot \"%s\"", STRING(m_iszCameraName) ) );

	// Now take the shot next frame
	SetThink( &CPointDevShotCamera::DevShotThink_PostShot );
	SetNextThink( gpGlobals->curtime + (DEVSHOT_INTERVAL - 1) );
}
//This example gets the current map name, and appends it onto the end of a prefix string
//It's used to find per-map files, such as custom soundscapes.
const char *mapname = STRING( gpGlobals->mapname );
const char *mapSoundscapeFilename = NULL;
if ( mapname && *mapname )
{
	mapSoundscapeFilename = UTIL_VarArgs( "scripts/soundscapes_%s.txt", mapname );
}
//This example just prints the player's current eye angles when called.
CBasePlayer *pPlayer = UTIL_GetCommandClient();
if (!pPlayer)
    return;
char *pOutput = UTIL_VarArgs( "Player X: %.2f, Y: %.2f, Z: %.2f\n", pPlayer->EyeAngles().x, pPlayer->EyeAngles().y, pPlayer->EyeAngles().z );
Msg( "%s", pOutput );