[cJass] cj_print (string formatting) - discussion

09-02-2009, 07:02 PM

What is this all about?

Since AdicParser v1.3.4.0 we introduced really exciting feature called string format function!
We have released cj_print (the library include file), where some basic macros and type handlers for string formatting are available. The main objective of this addition is to improve code readability.
One noticeable thing is that formatting affects only new functions - any other strings will remain untouched. =)

Example:

void Trig_esc_Actions () {
    printf ("^pc was defeated by evil ^pc - he lost ^igold gold.", Player(0), Player(1), GetRandomInt(0,1))
//  printf ("%pc was defeated by evil %pc - he lost %igold gold.", Player(0), Player(1), GetRandomInt(0,1))
//  use '%' only outside of custom script section  
//  both '^' and '%' signs serve the same purpose, 
//  but '%' cannot be used inside of Custom Script section because of World Editor bug 
}

Output:

Well, then how can I use it?

First, make sure that you are using cJass(it can be obtained here http://cjass.xgm.ru )
Then, include the library: include "cj_print.j"
...and voila, pizdec! Now you can use new functions! You should remember that format string has to be followed with formatting arguments. In current version the argument limit equals to 16, but can be easily extended without hard-recoding.

What are the functions?

The function sprintf formats and returns a string as a result. As the "^" symbol is used for format type specifications, you can escape it ("\^") to use in the formatted string.

For example:

string s = sprintf ("hello, ^ipc! \^\^", 0)

All the other functions take format string and arg list among their other arguments (and yeah, they don't have to be the last ones). Here is the list of all new functions (format is the formatting string and ... is the formatting arguments list) and their default types.

Function list:

string sprintf                      (string format, ...)
void   printf                       (string format, ...) // standard game output
void   sBJDebugMsg                  (string format, ...)
void   sDisplayTextToPlayer         (player p, real x, real y, string format, ...)
void   sDisplayTimedTextToPlayer    (player p, real x, real y, real time,string format, ...)
void   sDisplayTimedTextFromPlayer  (player p, real x, real y, real time, string format, ...)
void   sSetTextTagText              (texttag t, string format, ..., real h)
void   sQuestSetTitle               (quest q, string format, ...)
void   sQuestSetDescription         (quest q, string format, ...)
void   sQuestItemSetDescription     (questitem q, string format, ...)
void   sMultiboardSetTitleText      (multiboard m, string format, ...)
void   sMultiboardSetItemsValue     (multiboard m, string format, ...)
void   sMultiboardSetItemValue      (multiboarditem m, string format, ...)
void   sDialogSetMessage            (dialog d, string format, ...)
button sDialogAddButton             (dialog d, string format, ..., int hotkey)
button sDialogAddQuitButton         (dialog d, bool b,string format, ..., int hotkey)
void   sLeaderboardAddItem          (leaderboard l, string format, ..., player p)

Default types:

^p	player name, takes player variable
^pc	colored player name, takes player variable
^i	decimal number, takes integer
^igold	decimal number, gold-colored, takes integer
^ilumb	decimal number, lumber-colored, takes integer
^ip	player name, takes integer (player id)
^ipc	colored player name, takes integer (player id)
^b	boolean, prints "true" or "false"
^r	floating number without extra formatting, takes real
^s	string, if a direct value is passed, it will be cleanly merged
^v	variable, an argument is directly placed
^h	decimal number, descriptor id is passed as an argument

What about my type?

The library is built in such a way, so the end-user can redefine the way types are processed or add his own types. You just have to redefine one macro:

JASS:

// here we define our own handlers
setdef cj_sprintf_argTyp_User = /* markup */

// here we use prints with our markup eg. in our library

// here we roll back to default markup
setdef cj_sprintf_argTyp_User =

The markup definition syntax will be described later.

Why is this good?

This is good because 99% of string processing is done on map compile stage do your map leaves optimized. But this also introduces one limitation: dynamic format specifications cannot be used.

09-03-2009, 09:47 AM	#2
Toadcop	looks awesome but i have no use for it ^_^

09-03-2009, 01:12 PM

Vexorian

Quote:

This is good because 99% of string processing is done on map compile stage do your map leaves optimized.

nah, it wouldn't improve speed that much it is more of a making things easier thing.

I don´t get why call it cJass when the syntax tries to get some different from good old C, I mean why not use %? ^ is kind of hard to access in most keyboards I've used.

09-03-2009, 01:47 PM

Van Damm

Quote:

Originally Posted by Vexorian

I don´t get why call it cJass

It's because this file is part of cJass standard library and AdicHelper does the processing.

Quote:

Originally Posted by Vexorian

I mean why not use %?

The reason is World Editor does strange things with % symbol inside of strings when saving the map.

09-03-2009, 05:54 PM	#5
Vexorian	That only happened on the custom script section (which nobody on his own mind should use). And I've had reports of it getting fixed in 1.24.

09-03-2009, 06:58 PM	#6
Van Damm	Thanks for the tip. We'll implement % as well. Anyway, I've just tested % in Custom Script, and it's still messed up even in 1.24b

09-03-2009, 07:04 PM	#7
ADOLF	But we won't remove ^ for compatibility and to be able to use string formatting in custom script (if anyone wants to)

09-07-2009, 09:36 AM	#8
Van Damm	'%' sign as a control sequence starter added in AdicHelper 1.3.4.7. Now you can equally use % and ^ signs.