openttd-ottdgrfs: comparison src/strings.cpp

equal deleted inserted replaced

-:3b068c3a1c74
+:0fa543611bbe
 /* $Id$ */
+/** @file strings.cpp */
 #include "stdafx.h"
 #include "openttd.h"
 #include "currency.h"
 #include "functions.h"
 static char *GetSpecialPlayerNameString(char *buff, int ind, const int32 *argv, const char* last);
 static char *FormatString(char *buff, const char *str, const int32 *argv, uint casei, const char* last);
 struct LanguagePack {
-	uint32 ident;
+	uint32 ident;       // 32-bits identifier
 	uint32 version;     // 32-bits of auto generated version info which is basically a hash of strings.h
 	char name[32];      // the international name of this language
 	char own_name[32];  // the localized name of this language
 	char isocode[16];   // the ISO code for the language (not country code)
 	uint16 offsets[32]; // the offsets
 	byte plural_form;   // how to compute plural forms
 	byte pad[3];        // pad header to be a multiple of 4
-	char data[VARARRAY_SIZE];
+	char data[VARARRAY_SIZE]; // list of strings
 };
 static char **_langpack_offs;
 static LanguagePack *_langpack;
-static uint _langtab_num[32]; // Offset into langpack offs
+static uint _langtab_num[32];   // Offset into langpack offs
 static uint _langtab_start[32]; // Offset into langpack offs
-// Read an int64 from the argv array.
+/** Read an int64 from the argv array. */
 static inline int64 GetInt64(const int32 **argv)
 {
 	int64 result;
 	assert(argv);
 	result = (uint32)(*argv)[0] + ((uint64)(uint32)(*argv)[1] << 32);
 	(*argv)+=2;
 	return result;
 }
-// Read an int32 from the argv array.
+/** Read an int32 from the argv array. */
 static inline int32 GetInt32(const int32 **argv)
 {
 	assert(argv);
 	return *(*argv)++;
 }
-// Read an array from the argv array.
+/** Read an array from the argv array. */
 static inline const int32 *GetArgvPtr(const int32 **argv, int n)
 {
 	const int32 *result;
 	assert(*argv);
 	result = *argv;
 }
 #define NUM_BOUND_STRINGS 8
-// Array to hold the bound strings.
+/* Array to hold the bound strings. */
 static const char *_bound_strings[NUM_BOUND_STRINGS];
-// This index is used to implement a "round-robin" allocating of
+/* This index is used to implement a "round-robin" allocating of
-// slots for BindCString. NUM_BOUND_STRINGS slots are reserved.
+* slots for BindCString. NUM_BOUND_STRINGS slots are reserved.
-// Which means that after NUM_BOUND_STRINGS calls to BindCString,
+* Which means that after NUM_BOUND_STRINGS calls to BindCString,
-// the indices will be reused.
+* the indices will be reused. */
 static int _bind_index;
 static const char *GetStringPtr(StringID string)
 {
 	return _langpack_offs[_langtab_start[string >> 11] + (string & 0x7FF)];
 }
-// The highest 8 bits of string contain the "case index".
+/** The highest 8 bits of string contain the "case index".
-// These 8 bits will only be set when FormatString wants to print
+* These 8 bits will only be set when FormatString wants to print
-// the string in a different case. No one else except FormatString
+* the string in a different case. No one else except FormatString
-// should set those bits, therefore string CANNOT be StringID, but uint32.
+* should set those bits, therefore string CANNOT be StringID, but uint32.
+* @param buffr
+* @param string
+* @param argv
+* @param last
+* @return a formatted string of char
+*/
 static char *GetStringWithArgs(char *buffr, uint string, const int32 *argv, const char* last)
 {
 	uint index = GB(string,  0, 11);
 	uint tab   = GB(string, 11,  5);
 	char buff[512];
 		case 14:
 			if (index >= 0xE4)
 				return GetSpecialPlayerNameString(buffr, index - 0xE4, argv, last);
 			break;
-		// User defined name
 		case 15:
+			/* User defined name */
 			return GetName(buffr, index, last);
 		case 26:
 			/* Include string within newgrf text (format code 81) */
 			if (HASBIT(index, 10)) {
 		case 30:
 			GetGRFString(buff, index + 0x1000, lastof(buff));
 			return FormatString(buffr, buff, argv, 0, last);
 		case 31:
-			// dynamic strings. These are NOT to be passed through the formatter,
+			/* dynamic strings. These are NOT to be passed through the formatter,
-			// but passed through verbatim.
+			 * but passed through verbatim. */
 			if (index < (STR_SPEC_USERSTRING & 0x7FF)) {
 				return strecpy(buffr, _bound_strings[index], last);
 			}
 			return FormatString(buffr, _userstring, NULL, 0, last);
 /**
 * This function takes a C-string and allocates a temporary string ID.
 * The StringID of the bound string is valid until BindCString is called
 * another NUM_BOUND_STRINGS times. So be careful when using it.
-*
+* @param str temp string to add
+* @return the id of that temp string
 * @note formatting a DATE_TINY calls BindCString twice, thus reduces the
 *       amount of 'user' bound strings by 2.
 * @todo rewrite the BindCString system to make the limit flexible and
 *       non-round-robin. For example by using smart pointers that free
 *       the allocated StringID when they go out-of-scope/are freed.
 	int idx = (++_bind_index) & (NUM_BOUND_STRINGS - 1);
 	_bound_strings[idx] = str;
 	return idx + STR_SPEC_DYNSTRING;
 }
-// This function is used to "bind" a C string to a OpenTTD dparam slot.
+/** This function is used to "bind" a C string to a OpenTTD dparam slot.
+* @param n slot of the string
+* @param str string to bind
+*/
 void SetDParamStr(uint n, const char *str)
 {
 	SetDParam(n, BindCString(str));
 }
 	const char* multiplier = "";
 	char buf[40];
 	char* p;
 	int j;
-	// multiply by exchange rate
+	/* multiply by exchange rate */
 	number *= spec->rate;
-	// convert from negative
+	/* convert from negative */
 	if (number < 0) {
 		buff = strecpy(buff, "-", last);
 		number = -number;
 	}
 	/* Add prefix part, folowing symbol_pos specification.
 	 * Here, it can can be either 0 (prefix) or 2 (both prefix anf suffix).
 	 * The only remaining value is 1 (suffix), so everything that is not 1 */
 	if (spec->symbol_pos != 1) buff = strecpy(buff, spec->prefix, last);
-	// for huge numbers, compact the number into k or M
+	/* for huge numbers, compact the number into k or M */
 	if (compact) {
 		if (number >= 1000000000) {
 			number = (number + 500000) / 1000000;
 			multiplier = "M";
 		} else if (number >= 1000000) {
 			number = (number + 500) / 1000;
 			multiplier = "k";
 		}
 	}
-	// convert to ascii number and add commas
+	/* convert to ascii number and add commas */
 	p = endof(buf);
 	*--p = '\0';
 	j = 4;
 	do {
 		if (--j == 0) {
 	return buff;
 }
 static int DeterminePluralForm(int32 n)
 {
-	// The absolute value determines plurality
+	/* The absolute value determines plurality */
 	if (n < 0) n = -n;
 	switch (_langpack->plural_form) {
-	// Two forms, singular used for one only
+	/* Two forms, singular used for one only
-	// Used in:
+	 * Used in:
-	//   Danish, Dutch, English, German, Norwegian, Swedish, Estonian, Finnish,
+	 *   Danish, Dutch, English, German, Norwegian, Swedish, Estonian, Finnish,
-	//   Greek, Hebrew, Italian, Portuguese, Spanish, Esperanto
+	 *   Greek, Hebrew, Italian, Portuguese, Spanish, Esperanto */
 	case 0:
 	default:
 		return n != 1;
-	// Only one form
+	/* Only one form
-	// Used in:
+	 * Used in:
-	//   Hungarian, Japanese, Korean, Turkish
+	 *   Hungarian, Japanese, Korean, Turkish */
 	case 1:
 		return 0;
-	// Two forms, singular used for zero and one
+	/* Two forms, singular used for zero and one
-	// Used in:
+	 * Used in:
-	//   French, Brazilian Portuguese
+	 *   French, Brazilian Portuguese */
 	case 2:
 		return n > 1;
-	// Three forms, special case for zero
+	/* Three forms, special case for zero
-	// Used in:
+	 * Used in:
-	//   Latvian
+	 *   Latvian */
 	case 3:
 		return n%10==1 && n%100!=11 ? 0 : n != 0 ? 1 : 2;
-	// Three forms, special case for one and two
+	/* Three forms, special case for one and two
-	// Used in:
+	 * Used in:
-	//   Gaelige (Irish)
+	 *   Gaelige (Irish) */
 	case 4:
 		return n==1 ? 0 : n==2 ? 1 : 2;
-	// Three forms, special case for numbers ending in 1[2-9]
+	/* Three forms, special case for numbers ending in 1[2-9]
-	// Used in:
+	 * Used in:
-	//   Lithuanian
+	 *   Lithuanian */
 	case 5:
 		return n%10==1 && n%100!=11 ? 0 : n%10>=2 && (n%100<10 || n%100>=20) ? 1 : 2;
-	// Three forms, special cases for numbers ending in 1 and 2, 3, 4, except those ending in 1[1-4]
+	/* Three forms, special cases for numbers ending in 1 and 2, 3, 4, except those ending in 1[1-4]
-	// Used in:
+	 * Used in:
-	//   Croatian, Czech, Russian, Slovak, Ukrainian
+	 *   Croatian, Czech, Russian, Slovak, Ukrainian */
 	case 6:
 		return n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
-	// Three forms, special case for one and some numbers ending in 2, 3, or 4
+	/* Three forms, special case for one and some numbers ending in 2, 3, or 4
-	// Used in:
+	 * Used in:
-	//   Polish
+	 *   Polish */
 	case 7:
 		return n==1 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
-	// Four forms, special case for one and all numbers ending in 02, 03, or 04
+	/* Four forms, special case for one and all numbers ending in 02, 03, or 04
-	// Used in:
+	 * Used in:
-	//   Slovenian
+	 *   Slovenian */
 	case 8:
 		return n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3;
 	}
 }
 			case SCC_REVISION: /* {REV} */
 				buff = strecpy(buff, _openttd_revision, last);
 				break;
 			case SCC_CARGO_SHORT: { /* {SHORTCARGO} */
-				// Short description of cargotypes. Layout:
+				/* Short description of cargotypes. Layout:
-				// 8-bit = cargo type
+				 * 8-bit = cargo type
-				// 16-bit = cargo count
+				 * 16-bit = cargo count */
 				StringID cargo_str = GetCargo(GetInt32(&argv))->units_volume;
 				switch (cargo_str) {
 					case STR_TONS: {
 						int32 args[1];
 						assert(_opt_ptr->units < lengthof(units));
 						break;
 				}
 			} break;
 			case SCC_CURRENCY_COMPACT_64: { /* {CURRCOMPACT64} */
-				// 64 bit compact currency-unit
+				/* 64 bit compact currency-unit */
 				buff = FormatGenericCurrency(buff, _currency, GetInt64(&argv), true, last);
 				break;
 			}
 			case SCC_STRING1: { /* {STRING1} */
-				// String that consumes ONE argument
+				/* String that consumes ONE argument */
 				uint str = modifier + GetInt32(&argv);
 				buff = GetStringWithArgs(buff, str, GetArgvPtr(&argv, 1), last);
 				modifier = 0;
 				break;
 			}
 			case SCC_STRING2: { /* {STRING2} */
-				// String that consumes TWO arguments
+				/* String that consumes TWO arguments */
 				uint str = modifier + GetInt32(&argv);
 				buff = GetStringWithArgs(buff, str, GetArgvPtr(&argv, 2), last);
 				modifier = 0;
 				break;
 			}
 			case SCC_STRING3: { /* {STRING3} */
-				// String that consumes THREE arguments
+				/* String that consumes THREE arguments */
 				uint str = modifier + GetInt32(&argv);
 				buff = GetStringWithArgs(buff, str, GetArgvPtr(&argv, 3), last);
 				modifier = 0;
 				break;
 			}
 			case SCC_STRING4: { /* {STRING4} */
-				// String that consumes FOUR arguments
+				/* String that consumes FOUR arguments */
 				uint str = modifier + GetInt32(&argv);
 				buff = GetStringWithArgs(buff, str, GetArgvPtr(&argv, 4), last);
 				modifier = 0;
 				break;
 			}
 			case SCC_STRING5: { /* {STRING5} */
-				// String that consumes FIVE arguments
+				/* String that consumes FIVE arguments */
 				uint str = modifier + GetInt32(&argv);
 				buff = GetStringWithArgs(buff, str, GetArgvPtr(&argv, 5), last);
 				modifier = 0;
 				break;
 			}
 			case SCC_INDUSTRY_NAME: { /* {INDUSTRY} */
 				const Industry* i = GetIndustry(GetInt32(&argv));
 				int32 args[2];
-				// industry not valid anymore?
+				/* industry not valid anymore? */
 				if (!IsValidIndustry(i)) break;
-				// First print the town name and the industry type name
+				/* First print the town name and the industry type name
-				// The string STR_INDUSTRY_PATTERN controls the formatting
+				 * The string STR_INDUSTRY_PATTERN controls the formatting */
 				args[0] = i->town->index;
 				args[1] = GetIndustrySpec(i->type)->name;
 				buff = FormatString(buff, GetStringPtr(STR_INDUSTRY_FORMAT), args, modifier >> 24, last);
 				modifier = 0;
 				break;
 				buff = FormatTinyDate(buff, GetInt32(&argv), last);
 				break;
 			}
 			case SCC_CARGO: { // {CARGO}
-				// Layout now is:
+				/* Layout now is:
-				//   8bit   - cargo type
+				 *   8bit   - cargo type
-				//   16-bit - cargo count
+				 *   16-bit - cargo count */
 				CargoID cargo = GetInt32(&argv);
 				StringID cargo_str = (cargo == CT_INVALID) ? (StringID)STR_8838_N_A : GetCargo(cargo)->quantifier;
 				buff = GetStringWithArgs(buff, cargo_str, argv++, last);
 				break;
 			}
 			case SCC_SKIP: // {SKIP}
 				argv++;
 				break;
-			// This sets up the gender for the string.
+			/* This sets up the gender for the string.
-			// We just ignore this one. It's used in {G 0 Der Die Das} to determine the case.
+			 * We just ignore this one. It's used in {G 0 Der Die Das} to determine the case. */
 			case SCC_GENDER_INDEX: // {GENDER 0}
 				str++;
 				break;
 			case SCC_STRING: {// {STRING}
 				uint str = modifier + GetInt32(&argv);
-				// WARNING. It's prohibited for the included string to consume any arguments.
+				/* WARNING. It's prohibited for the included string to consume any arguments.
-				// For included strings that consume argument, you should use STRING1, STRING2 etc.
+				 * For included strings that consume argument, you should use STRING1, STRING2 etc.
-				// To debug stuff you can set argv to NULL and it will tell you
+				 * To debug stuff you can set argv to NULL and it will tell you */
 				buff = GetStringWithArgs(buff, str, argv, last);
 				modifier = 0;
 				break;
 			}
 				buff = FormatGenericCurrency(buff, _currency, GetInt64(&argv), false, last);
 				break;
 			}
 			case SCC_SETCASE: { // {SETCASE}
-				// This is a pseudo command, it's outputted when someone does {STRING.ack}
+				/* This is a pseudo command, it's outputted when someone does {STRING.ack}
-				// The modifier is added to all subsequent GetStringWithArgs that accept the modifier.
+				 * The modifier is added to all subsequent GetStringWithArgs that accept the modifier. */
 				modifier = (byte)*str++ << 24;
 				break;
 			}
 			case SCC_SWITCH_CASE: { // {Used to implement case switching}
-				// <0x9E> <NUM CASES> <CASE1> <LEN1> <STRING1> <CASE2> <LEN2> <STRING2> <CASE3> <LEN3> <STRING3> <STRINGDEFAULT>
+				/* <0x9E> <NUM CASES> <CASE1> <LEN1> <STRING1> <CASE2> <LEN2> <STRING2> <CASE3> <LEN3> <STRING3> <STRINGDEFAULT>
-				// Each LEN is printed using 2 bytes in big endian order.
+				 * Each LEN is printed using 2 bytes in big endian order. */
 				uint num = (byte)*str++;
 				while (num) {
 					if ((byte)str[0] == casei) {
-						// Found the case, adjust str pointer and continue
+						/* Found the case, adjust str pointer and continue */
 						str += 3;
 						break;
 					}
-					// Otherwise skip to the next case
+					/* Otherwise skip to the next case */
 					str += 3 + (str[1] << 8) + str[2];
 					num--;
 				}
 				break;
 			}
 		case 4: // song names
 			return strecpy(buff, origin_songs_specs[GetInt32(&argv) - 1].song_name, last);
 	}
-	// town name?
+	/* town name? */
 	if (IS_INT_INSIDE(ind - 6, 0, SPECSTR_TOWNNAME_LAST-SPECSTR_TOWNNAME_START + 1)) {
 		buff = GetSpecialTownNameString(buff, ind - 6, GetInt32(&argv), last);
 		return strecpy(buff, " Transport", last);
 	}
-	// language name?
+	/* language name? */
 	if (IS_INT_INSIDE(ind, (SPECSTR_LANGUAGE_START - 0x70E4), (SPECSTR_LANGUAGE_END - 0x70E4) + 1)) {
 		int i = ind - (SPECSTR_LANGUAGE_START - 0x70E4);
 		return strecpy(buff,
 			i == _dynlang.curr ? _langpack->own_name : _dynlang.ent[i].name, last);
 	}
-	// resolution size?
+	/* resolution size? */
 	if (IS_INT_INSIDE(ind, (SPECSTR_RESOLUTION_START - 0x70E4), (SPECSTR_RESOLUTION_END - 0x70E4) + 1)) {
 		int i = ind - (SPECSTR_RESOLUTION_START - 0x70E4);
 		buff += snprintf(
 			buff, last - buff + 1, "%dx%d", _resolutions[i][0], _resolutions[i][1]
 		);
 		return buff;
 	}
-	// screenshot format name?
+	/* screenshot format name? */
 	if (IS_INT_INSIDE(ind, (SPECSTR_SCREENSHOT_START - 0x70E4), (SPECSTR_SCREENSHOT_END - 0x70E4) + 1)) {
 		int i = ind - (SPECSTR_SCREENSHOT_START - 0x70E4);
 		return strecpy(buff, GetScreenshotFormatDesc(i), last);
 	}
 	assert(0);
 	return NULL;
 }
-// remap a string ID from the old format to the new format
+/**
+* remap a string ID from the old format to the new format
+* @param s StringID that requires remapping
+* @return translated ID*/
 StringID RemapOldStringID(StringID s)
 {
 	switch (s) {
 		case 0x0006: return STR_SV_EMPTY;
 		case 0x7000: return STR_SV_UNNAMED;
 		_langtab_start[i] = tot_count;
 		_langtab_num[i] = num;
 		tot_count += num;
 	}
-	// Allocate offsets
+	/* Allocate offsets */
 	langpack_offs = MallocT<char*>(tot_count);
-	// Fill offsets
+	/* Fill offsets */
 	s = lang_pack->data;
 	for (i = 0; i != tot_count; i++) {
 		len = (byte)*s;
 		*s++ = '\0'; // zero terminate the string before.
 		if (len >= 0xC0) len = ((len & 0x3F) << 8) + (byte)*s++;
 }
 /** Determine the current charset based on the environment
 * First check some default values, after this one we passed ourselves
 * and if none exist return the value for $LANG
-* @param environment variable to check conditionally if default ones are not
+* @param param environment variable to check conditionally if default ones are not
 *        set. Pass NULL if you don't want additional checks.
 * @return return string containing current charset, or NULL if not-determinable */
 const char *GetCurrentLocale(const char *param)
 {
 	const char *env;

branch	gamebalance
changeset 9908	0fa543611bbe
parent 9906	6f41b8713b65
child 9910	0b2aebc8283e