|
The HLA Standard Library's string module contains dozens of routines for converting between strings and other data formats. Although it's a little premature in this text to present a complete description of those functions, it would be rather criminal not to discuss at least one of the available functions: the str.put routine. This one routine (which is actually a macro) encapsulates the capabilities of all the other string conversion functions, so if you learn how to use this one, you'll have most of the capabilities of those other routines at your disposal. For more information on the other string conversions, check out the HLA Standard Library documentation.
You use the str.put routine in a manner very similar to the stdout.put routine. The only difference is that the str.put routine "writes" its data to a string instead of the standard output device. A call to str.put has the following syntax:
str.put( destString, values_to_convert );
Example of a call to str.put:
str.put( destString, "I =", i:4, " J= ", j, " s=", s );
Note | Generally, you would not put a newline character sequence at the end of the string as you would if you were printing the string to the standard output device. |
The destString parameter at the beginning of the str.put parameter list must be a string variable, and it must already have storage associated with it. If str.put attempts to store more characters than allowed into the destString parameter, then this function raises the ex.StringOverflow exception.
Most of the time you won't know the length of the string that str.put will produce. In those instances, you should simply allocate sufficient storage for a really large string, one that is way larger than you expect, and use this string data as the first parameter of the str.put call. This will prevent an exception from crashing your program. Generally, if you expect to produce about one screen line of text, you should probably allocate at least 256 characters for the destination string. If you're creating longer strings, you should probably use a default of 1024 characters (or more, if you're going to produce really large strings).
Example:
static s: string; . . . stralloc( 256 ); mov( eax, s ); . . . str.put( s, "R: ", r:16:4, "strval: '", strval:-10, "'");
You can use the str.put routine to convert any data to a string that you can print using stdout.put. You will probably find this routine invaluable for common value-to-string conversions.
At the time of this writing, there is no corresponding str.get routine that will read values from an input string (this routine will probably appear in a future version of the HLA Standard Library, so watch out for it). In the meantime, the HLA strings and conversions modules in the Standard Library do provide several stand-alone conversion functions you can use to convert string data to some other format. See the HLA Standard Library documentation for more details about these routines.
|