diff options
author | belugas <belugas@openttd.org> | 2007-04-04 01:35:16 +0000 |
---|---|---|
committer | belugas <belugas@openttd.org> | 2007-04-04 01:35:16 +0000 |
commit | dfe5533db674cf2f21652f91cf626831a22344ec (patch) | |
tree | c8c468b064c05fa682d00013b36792570a637721 /src/strings.cpp | |
parent | f12d1a3f0a0978464dad84c1b31752aece298321 (diff) | |
download | openttd-dfe5533db674cf2f21652f91cf626831a22344ec.tar.xz |
(svn r9556) -Documentation: doxygen and comment-style changes. 'R', 'S'.. The end of the preliminary work is near
Diffstat (limited to 'src/strings.cpp')
-rw-r--r-- | src/strings.cpp | 189 |
1 files changed, 102 insertions, 87 deletions
diff --git a/src/strings.cpp b/src/strings.cpp index d7f3ecfd6..d36edc2e7 100644 --- a/src/strings.cpp +++ b/src/strings.cpp @@ -1,5 +1,7 @@ /* $Id$ */ +/** @file strings.cpp */ + #include "stdafx.h" #include "openttd.h" #include "currency.h" @@ -37,7 +39,7 @@ static char *GetSpecialPlayerNameString(char *buff, int ind, const int32 *argv, 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 @@ -45,16 +47,16 @@ struct LanguagePack { 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; @@ -65,14 +67,14 @@ static inline int64 GetInt64(const int32 **argv) 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; @@ -85,13 +87,13 @@ static inline const int32 *GetArgvPtr(const int32 **argv, int n) #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 -// slots for BindCString. NUM_BOUND_STRINGS slots are reserved. -// Which means that after NUM_BOUND_STRINGS calls to BindCString, -// the indices will be reused. +/* This index is used to implement a "round-robin" allocating of + * slots for BindCString. NUM_BOUND_STRINGS slots are reserved. + * Which means that after NUM_BOUND_STRINGS calls to BindCString, + * the indices will be reused. */ static int _bind_index; static const char *GetStringPtr(StringID string) @@ -99,10 +101,16 @@ 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". -// These 8 bits will only be set when FormatString wants to print -// the string in a different case. No one else except FormatString -// should set those bits, therefore string CANNOT be StringID, but uint32. +/** The highest 8 bits of string contain the "case index". + * These 8 bits will only be set when FormatString wants to print + * the string in a different case. No one else except FormatString + * 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); @@ -122,8 +130,8 @@ static char *GetStringWithArgs(char *buffr, uint string, const int32 *argv, cons return GetSpecialPlayerNameString(buffr, index - 0xE4, argv, last); break; - // User defined name case 15: + /* User defined name */ return GetName(buffr, index, last); case 26: @@ -147,8 +155,8 @@ static char *GetStringWithArgs(char *buffr, uint string, const int32 *argv, cons return FormatString(buffr, buff, argv, 0, last); case 31: - // dynamic strings. These are NOT to be passed through the formatter, - // but passed through verbatim. + /* dynamic strings. These are NOT to be passed through the formatter, + * but passed through verbatim. */ if (index < (STR_SPEC_USERSTRING & 0x7FF)) { return strecpy(buffr, _bound_strings[index], last); } @@ -184,7 +192,8 @@ char *InlineString(char *buf, StringID string) * 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 @@ -198,7 +207,10 @@ StringID BindCString(const char *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)); @@ -331,10 +343,10 @@ static char *FormatGenericCurrency(char *buff, const CurrencySpec *spec, int64 n 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; @@ -345,7 +357,7 @@ static char *FormatGenericCurrency(char *buff, const CurrencySpec *spec, int64 n * 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; @@ -356,7 +368,7 @@ static char *FormatGenericCurrency(char *buff, const CurrencySpec *spec, int64 n } } - // convert to ascii number and add commas + /* convert to ascii number and add commas */ p = endof(buf); *--p = '\0'; j = 4; @@ -381,63 +393,63 @@ static char *FormatGenericCurrency(char *buff, const CurrencySpec *spec, int64 n 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 - // Used in: - // Danish, Dutch, English, German, Norwegian, Swedish, Estonian, Finnish, - // Greek, Hebrew, Italian, Portuguese, Spanish, Esperanto + /* Two forms, singular used for one only + * Used in: + * Danish, Dutch, English, German, Norwegian, Swedish, Estonian, Finnish, + * Greek, Hebrew, Italian, Portuguese, Spanish, Esperanto */ case 0: default: return n != 1; - // Only one form - // Used in: - // Hungarian, Japanese, Korean, Turkish + /* Only one form + * Used in: + * Hungarian, Japanese, Korean, Turkish */ case 1: return 0; - // Two forms, singular used for zero and one - // Used in: - // French, Brazilian Portuguese + /* Two forms, singular used for zero and one + * Used in: + * French, Brazilian Portuguese */ case 2: return n > 1; - // Three forms, special case for zero - // Used in: - // Latvian + /* Three forms, special case for zero + * Used in: + * Latvian */ case 3: return n%10==1 && n%100!=11 ? 0 : n != 0 ? 1 : 2; - // Three forms, special case for one and two - // Used in: - // Gaelige (Irish) + /* Three forms, special case for one and two + * Used in: + * Gaelige (Irish) */ case 4: return n==1 ? 0 : n==2 ? 1 : 2; - // Three forms, special case for numbers ending in 1[2-9] - // Used in: - // Lithuanian + /* Three forms, special case for numbers ending in 1[2-9] + * Used in: + * 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] - // Used in: - // Croatian, Czech, Russian, Slovak, Ukrainian + /* Three forms, special cases for numbers ending in 1 and 2, 3, 4, except those ending in 1[1-4] + * Used in: + * 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 - // Used in: - // Polish + /* Three forms, special case for one and some numbers ending in 2, 3, or 4 + * Used in: + * 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 - // Used in: - // Slovenian + /* Four forms, special case for one and all numbers ending in 02, 03, or 04 + * Used in: + * Slovenian */ case 8: return n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3; } @@ -561,9 +573,9 @@ static char* FormatString(char* buff, const char* str, const int32* argv, uint c break; case SCC_CARGO_SHORT: { /* {SHORTCARGO} */ - // Short description of cargotypes. Layout: - // 8-bit = cargo type - // 16-bit = cargo count + /* Short description of cargotypes. Layout: + * 8-bit = cargo type + * 16-bit = cargo count */ StringID cargo_str = GetCargo(GetInt32(&argv))->units_volume; switch (cargo_str) { case STR_TONS: { @@ -599,13 +611,13 @@ static char* FormatString(char* buff, const char* str, const int32* argv, uint c } 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; @@ -613,7 +625,7 @@ static char* FormatString(char* buff, const char* str, const int32* argv, uint c } 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; @@ -621,7 +633,7 @@ static char* FormatString(char* buff, const char* str, const int32* argv, uint c } 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; @@ -629,7 +641,7 @@ static char* FormatString(char* buff, const char* str, const int32* argv, uint c } 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; @@ -637,7 +649,7 @@ static char* FormatString(char* buff, const char* str, const int32* argv, uint c } 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; @@ -653,11 +665,11 @@ static char* FormatString(char* buff, const char* str, const int32* argv, uint c 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 - // The string STR_INDUSTRY_PATTERN controls the formatting + /* First print the town name and the industry type name + * 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); @@ -690,9 +702,9 @@ static char* FormatString(char* buff, const char* str, const int32* argv, uint c } case SCC_CARGO: { // {CARGO} - // Layout now is: - // 8bit - cargo type - // 16-bit - cargo count + /* Layout now is: + * 8bit - cargo type + * 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); @@ -748,17 +760,17 @@ static char* FormatString(char* buff, const char* str, const int32* argv, uint c argv++; break; - // 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. + /* 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. */ 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. - // 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 + /* WARNING. It's prohibited for the included string to consume any arguments. + * 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 */ buff = GetStringWithArgs(buff, str, argv, last); modifier = 0; break; @@ -834,23 +846,23 @@ static char* FormatString(char* buff, const char* str, const int32* argv, uint c } case SCC_SETCASE: { // {SETCASE} - // 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. + /* 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. */ 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> - // Each LEN is printed using 2 bytes in big endian order. + /* <0x9E> <NUM CASES> <CASE1> <LEN1> <STRING1> <CASE2> <LEN2> <STRING2> <CASE3> <LEN3> <STRING3> <STRINGDEFAULT> + * 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--; } @@ -1018,20 +1030,20 @@ static char *GetSpecialPlayerNameString(char *buff, int ind, const int32 *argv, 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( @@ -1040,7 +1052,7 @@ static char *GetSpecialPlayerNameString(char *buff, int ind, const int32 *argv, 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); @@ -1050,7 +1062,10 @@ static char *GetSpecialPlayerNameString(char *buff, int ind, const int32 *argv, 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) { @@ -1103,10 +1118,10 @@ bool ReadLanguagePack(int lang_index) 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; @@ -1133,7 +1148,7 @@ bool ReadLanguagePack(int lang_index) /** 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) |