1/*! 2\class BLocale 3\ingroup locale 4\brief Class for representing a locale and its settings. 5 6A locale is defined by the combination of a country and a language. Using these 7two informations, it is possible to determine the format to use for date, time, 8and number formatting. The BLocale class also provide collators, which allows 9you to sort a list of strings properly depending on a set of rules about 10accented chars and other special cases that vary over the different locales. 11 12BLocale is also the class to use when you want to perform formatting or parsing 13of dates, times, and numbers, in the natural language of the user. 14 15*/ 16 17/*! 18\fn const BCollator* BLocale::Collator() const 19\brief Returns the collator associated to this locale. 20 21Returns the collator in use for this locale, allowing you to use it to sort a 22set of strings. 23 24*/ 25 26/*! 27\fn const BCountry* BLocale::Country() const 28\brief Returns the country associated to this locale. 29 30A locale is defined by the combination of a country and a language. This 31method gets the country part of this information, so you can access the 32data that is not language-dependant (such as the country flag). 33 34*/ 35 36/*! 37\fn const BLanguage* BLocale::Language() const 38\brief Returns the language associated to this locale. 39 40*/ 41 42/*! 43\fn const char* BLocale::Code() const 44\brief Returns the locale code. 45 46This function returns the locale name (such as en_US for united states english). 47*/ 48 49/*! 50\fn bool BLocale::GetName(BString& name) const 51\brief Get the name of the locale. 52 53This function fills the name string with the localized name of this locale. 54For example, if the locale us en_US and the user language is french, this function will return "anglais (Etats-Unis)". 55*/ 56 57/*! 58\fn void BLocale::SetCountry(const BCountry& newCountry) 59\brief Set the country for this locale. 60*/ 61 62/*! 63\fn void BLocale::SetCollator(const BCollator& newCollator) 64\brief Set the collator for this locale. 65*/ 66 67/*! 68\fn void BLocale::SetLanguage(const char* languageCode) 69\brief Set the language for this locale. 70*/ 71 72/*! 73\fn status_t BLocale::FormatDate(char* string, size_t maxSize, time_t time, bool longFormat) 74\brief Format a date. 75 76Fills in the string with a formatted date. The longFormat parameter allows you 77to select the short or the full format. 78 79\param string The string buffer to fill with the formated date. 80\param maxSize The size of the buffer. 81\param time The time (in seconds since epoch) to format 82\param longFormat If true, uses the long format (with day name, full month name). If false, use the short format, 08/12/2010 or similar. 83*/ 84 85/*! 86\fn status_t BLocale::FormatDate(BString* string, time_t time, bool longFormat) 87\brief Formats a date to a BString. 88*/ 89 90/*! 91\fn status_t BLocale::FormatDate(BString* string, int*& fieldPositions, int& fieldCount, time_t time, bool longFormat) 92\brief Format a date and get information about the different fields. 93 94This works the same way as the other FormatDatz methods, but also gives you the 95offset of the beginning of each field in the date. This is useful if you need to 96split the date in different parts for an user-modifiable area (see the Time 97preflet for an example). 98 99To identify the content of each field, you can use GetDateFields. 100 101This function allocates the fieldPositions arrays, you have to free it when you 102are finished with it. 103 104\sa GetDateFields 105*/ 106 107/*! 108\fn status_t BLocale::GetDateFields(BDateElement*& fields, int& fieldCount, bool longFormat) const 109\brief Get the type of each field in this date format 110 111This function is most often used in combination with FormatDate. FormatDate 112gives you the offset of each field in a formated string, anf GetDateFields gives 113you the type of the field at a given offset. With these informations, you can 114handle the formatted date string as a list of fields that you can split and 115alter at will. 116 117*/ 118 119/*! 120\fn status_t BLocale::GetDateFormat(BString& format, bool longFormat) const 121\brief Get the date format string 122 123This function returns the string used internally to represent a date format. 124*/ 125 126/*! 127\fn status_t BLocale::SetDateFormat(const char* formatString, bool longFormat) 128\brief Set the date format for this locale 129 130Thisfunction allows you to define your own date format for specific purposes. 131*/ 132 133/*! 134\fn int BLocale::StartOfWeek() const 135\brief Returns the day used as start of week in this locale. 136 137*/ 138 139/*! 140\fn int BLocale::StringCompare(const char* s1, const char* s2) const 141\fn int BLocale::StringCompare(const BString* s1, const BString* s2) const 142\brief Compares two strings using the locale's collator 143 144These methods are short-hands to Collator()->StringCompare. 145 146*/ 147 148/*! 149\fn void BLocale::GetSortKey(const char* string, BString* key) const 150\brief Computes the sort key of a string 151 152This method is a short-hand to Collator()->GetSortKey. 153 154*/ 155