1/* 2 * Copyright 2011, Haiku, Inc. All Rights Reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Axel Dörfler, axeld@pinc-software.de. 7 * John Scipione, jscipione@gmail.com 8 * Oliver Tappe, zooey@hirschkaefer.de. 9 * 10 * Corresponds to: 11 * /trunk/headers/os/locale/Locale.h rev 42274 12 * /trunk/src/kits/locale/Locale.cpp rev 42274 13 */ 14 15 16/*! 17 \file Locale.h 18 \brief Provides the BLocale class. 19*/ 20 21 22/*! \class BLocale 23 \ingroup locale 24 \brief Class for representing a locale and its settings. 25 26 A locale is defined by the combination of a country and a language. 27 Using these two informations, it is possible to determine the format 28 to use for date, time, and number formatting. The BLocale class also 29 provide collators, which allows you to sort a list of strings properly 30 depending on a set of rules about accented chars and other special 31 cases that vary over the different locales. 32 33 BLocale is also the class to use when you want to perform formatting 34 or parsing of dates, times, and numbers, in the natural language of 35 the user. 36*/ 37 38 39/*! 40 \fn BLocale::BLocale(const BLanguage* language, 41 const BFormattingConventions* conventions) 42 \brief Initializes a BLocale object corresponding to the passed in 43 \a language and \a conventions. 44*/ 45 46 47/*! 48 \fn BLocale::BLocale(const BLocale& other) 49 \brief Initializes a BLocale object. 50*/ 51 52 53/*! 54 status_t BLocale::GetCollator(BCollator* collator) const 55 \brief Gets the collator associated to this locale. 56 57 Returns the collator in use for this locale, allowing you to use it 58 to sort a set of strings. 59*/ 60 61 62/*! 63 \fn BLocale& BLocale::operator=(const BLocale& other) 64*/ 65 66 67/*! 68 \fn BLocale::~BLocale() 69 \brief Destructor method. 70*/ 71 72 73/*! 74 \fn status_t BLocale::GetCollator(BCollator* collator) const 75 \brief Sets \a collator object to the default collator for the BLocale. 76 77 \param collator A pointer to a BCollator object to fill out. 78 79 \returns A status code. 80 \retval B_OK Everything went well. 81 \retval B_BAD_VALUE \c NULL \a collator object passed in. 82 \retval B_ERROR Unable to lock the BLocale. 83*/ 84 85 86/*! 87 \fn status_t BLocale::GetLanguage(BLanguage* language) const 88 \brief Sets \a language object to the default language for the BLocale. 89 90 \param language A pointer to a BLanguage object to fill out. 91 92 \returns A status code. 93 \retval B_OK Everything went well. 94 \retval B_BAD_VALUE \c NULL \a language object passed in. 95 \retval B_ERROR Unable to lock the BLocale. 96*/ 97 98 99/*! 100 \fn status_t BLocale::GetFormattingConventions( 101 BFormattingConventions* conventions) const 102 \brief Sets \a conventions object to the default formatting conventions 103 for the BLocale. 104 105 \param conventions A pointer to a BFormattingConventions object to fill out. 106 107 \returns A status code. 108 \retval B_OK Everything went well. 109 \retval B_BAD_VALUE \c NULL \a conventions object passed in. 110 \retval B_ERROR Unable to lock the BLocale. 111*/ 112 113 114/*! 115 \fn const char* BLocale::GetString(uint32 id) const 116 \brief Gets the language string for the locale. 117 118 \param id The locale \a id to get the language of. 119 120 \internal Assumes a certain order of the string bases. 121 122 \returns a blank string in the case of an error or the string "UTF-8" 123 if there is \a id is set to \a B_CODESET. 124*/ 125 126 127/*! 128 \fn void BLocale::SetFormattingConventions( 129 const BFormattingConventions& conventions) 130 \brief Sets the formatting convention for this locale. 131 132 \param conventions The formatting convention to set. 133*/ 134 135 136/*! 137 \fn void BLocale::SetCollator(const BCollator& newCollator) 138 \brief Set the collator for this locale. 139 140 \param newCollator The collator to set. 141*/ 142 143 144/*! 145 \fn void BLocale::SetLanguage(const BLanguage& newLanguage) 146 \brief Set the language for this locale. 147 148 \param newLanguage The code of the language to set to locale to. 149*/ 150 151 152/*! 153 \fn ssize_t BLocale::FormatDate(char* string, size_t maxSize, time_t time, 154 BDateFormatStyle style) const 155 \brief Fills in \a string with a formatted date up to \a maxSize bytes for 156 the given \a time and \a style for the locale. 157 158 \param string The string buffer to fill with the formatted date. 159 \param maxSize The size of the buffer. 160 \param time The time (in seconds since epoch) to format 161 \param style Specify the long format (with day name, full 162 month name) or the short format, 08/12/2010 or similar. 163 164 \returns The number of bytes written during the date formatting. 165 \retval B_ERROR Unable to lock the BLocale. 166 \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. 167 \retval B_BAD_VALUE CheckedArrayByteSink overflowed. 168 169 \sa BLocale::FormatDateTime(char* target, size_t maxSize, 170 time_t time, BDateFormatStyle dateStyle, 171 BTimeFormatStyle timeStyle) const 172 \sa BLocale::FormatTime(char* string, size_t maxSize, time_t time, 173 BTimeFormatStyle style) const 174*/ 175 176 177/*! 178 \fn status_t BLocale::FormatDate(BString *string, time_t time, 179 BDateFormatStyle style, const BTimeZone* timeZone) const 180 \brief Fills in \a string with a formatted date for the given 181 \a time, \a style, and \a timeZone for the locale. 182 183 \param string The string buffer to fill with the formatted date. 184 \param time The time (in seconds since epoch) to format 185 \param style Specify the long format (with day name, full 186 month name) or the short format, 08/12/2010 or similar. 187 \param timeZone The time zone. 188 189 \returns A status code. 190 \retval B_OK Everything went fine. 191 \retval B_ERROR Unable to lock the BLocale. 192 \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. 193 194 \sa BLocale::FormatDateTime(BString* target, time_t time, 195 BDateFormatStyle dateStyle, BTimeFormatStyle timeStyle, 196 const BTimeZone* timeZone) const 197 \sa status_t BLocale::FormatTime(BString* string, time_t time, 198 BTimeFormatStyle style, const BTimeZone* timeZone) const 199*/ 200 201 202/*! 203 \fn status_t BLocale::FormatDate(BString* string, int*& fieldPositions, 204 int& fieldCount, time_t time, BDateFormatStyle style) const 205 \brief Fills in \a string with a formatted date for the given 206 \a time and \a style for the locale. 207 208 \param string The string buffer to fill with the formatted date. 209 \param fieldPositions ??? 210 \param fieldCount ??? 211 \param time The time (in seconds since epoch) to format 212 \param style Specify the long format (with day name, full 213 month name) or the short format, 08/12/2010 or similar. 214 215 \returns A status code. 216 \retval B_OK Everything went fine. 217 \retval B_ERROR Unable to lock the BLocale or an error formatting the date. 218 \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. 219 220 \sa BLocale::FormatTime(BString* string, int*& fieldPositions, 221 int& fieldCount, time_t time, BTimeFormatStyle style) const 222*/ 223 224 225/*! 226 \fn status_t BLocale::GetDateFields(BDateElement*& fields, int& fieldCount, 227 BDateFormatStyle style) const 228 \brief Get the type of each field in the date format of the locale. 229 230 This function is most often used in combination with FormatDate(). 231 FormatDate() gives you the offset of each field in a formatted string, 232 and GetDateFields() gives you the type of the field at a given offset. 233 With these informations, you can handle the formatted date string as 234 a list of fields that you can split and alter at will. 235 236 \param fields Pointer to the fields object. 237 \param fieldCount The number of fields. 238 \param style Specify the long format (with day name, full 239 month name) or the short format, 08/12/2010 or similar. 240 241 \returns A status code. 242 \retval B_OK Everything went fine. 243 \retval B_ERROR Unable to lock the BLocale or an error getting the date 244 fields. 245 \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. 246 247 \sa BLocale::GetTimeFields(BDateElement*& fields, int& fieldCount, 248 BTimeFormatStyle style) const 249*/ 250 251 252/*! 253 \fn int BLocale::StartOfWeek() const 254 \brief Returns the number of the day used as start of week in this locale. 255 256 \returns a flag that indicates the day of the week that the week starts or 257 B_ERROR if there was an error. 258 \retval B_ERROR Unable to lock the BLocale. 259 \retval B_WEEK_START_SUNDAY If the beginning of the week starts on Sunday. 260 \retval B_WEEK_START_MONDAY If the beginning of the week starts on Monday. 261*/ 262 263 264/*! 265 \fn ssize_t BLocale::FormatDateTime(char* target, size_t maxSize, 266 time_t time, BDateFormatStyle dateStyle, 267 BTimeFormatStyle timeStyle) const 268 \brief Fills in \a string with a formatted datetime up to \a maxSize bytes 269 for the given \a time and \a style for the locale. 270 271 \param target The string buffer to fill with the formatted datetime. 272 \param maxSize The size of the buffer. 273 \param time The time (in seconds since epoch) to format 274 \param dateStyle Specify the long format or the short format of the date. 275 \param timeStyle Specify the long format or the short format of the time. 276 277 \returns The number of bytes written during the datetime formatting. 278 \retval B_ERROR Unable to lock the BLocale. 279 \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. 280 \retval B_BAD_VALUE CheckedArrayByteSink overflowed. 281 282 \sa BLocale::FormatDate(char* string, size_t maxSize, time_t time, 283 BDateFormatStyle style) const 284 \sa BLocale::FormatTime(char* string, size_t maxSize, time_t time, 285 BTimeFormatStyle style) const 286*/ 287 288 289/*! 290 \fn status_t BLocale::FormatDateTime(BString* target, time_t time, 291 BDateFormatStyle dateStyle, BTimeFormatStyle timeStyle, 292 const BTimeZone* timeZone) const 293 \brief Fills in \a string with a formatted datetime for the given 294 \a time, \a timeStyle, and \a timeZone for the locale. 295 296 \param target The string buffer to fill with the formatted date. 297 \param time The time (in seconds since epoch) to format 298 \param dateStyle Specify the long format or the short format of the date. 299 \param timeStyle Specify the long format or the short format of the time. 300 \param timeZone The time zone. 301 302 \returns A status code. 303 \retval B_OK Everything went fine. 304 \retval B_ERROR Unable to lock the BLocale. 305 \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. 306 307 \sa BLocale::FormatDate(BString *string, time_t time, 308 BDateFormatStyle style, const BTimeZone* timeZone) const 309 \sa status_t BLocale::FormatTime(BString* string, time_t time, 310 BTimeFormatStyle style, const BTimeZone* timeZone) const 311*/ 312 313 314/*! 315 \fn ssize_t BLocale::FormatTime(char* string, size_t maxSize, time_t time, 316 BTimeFormatStyle style) const 317 \brief Fills in \a string with a formatted date up to \a maxSize bytes for 318 the given \a time and \a style for the locale. 319 320 \param string The string buffer to fill with the formatted time. 321 \param maxSize The size of the buffer. 322 \param time The time (in seconds since epoch) to format 323 \param style Specify the long format or the short format. 324 325 \returns The number of bytes written during the time formatting. 326 \retval B_ERROR Unable to lock the BLocale. 327 \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. 328 \retval B_BAD_VALUE CheckedArrayByteSink overflowed. 329 330 \sa BLocale::FormatDate(char* string, size_t maxSize, time_t time, 331 BDateFormatStyle style) const 332 \sa BLocale::FormatDateTime(char* target, size_t maxSize, 333 time_t time, BDateFormatStyle dateStyle, 334 BTimeFormatStyle timeStyle) const 335*/ 336 337 338/*! 339 \fn status_t BLocale::FormatTime(BString* string, time_t time, 340 BTimeFormatStyle style, const BTimeZone* timeZone) const 341 \brief Fills in \a string with a formatted time for the given 342 \a time, \a style, and \a timeZone for the locale. 343 344 \param string The string buffer to fill with the formatted date. 345 \param time The time (in seconds since epoch) to format 346 \param style Specify the long format or the short format. 347 \param timeZone The time zone. 348 349 \returns A status code. 350 \retval B_OK Everything went fine. 351 \retval B_ERROR Unable to lock the BLocale. 352 \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. 353 354 \sa BLocale::FormatDate(BString *string, time_t time, 355 BDateFormatStyle style, const BTimeZone* timeZone) const 356 \sa BLocale::FormatDateTime(BString* target, time_t time, 357 BDateFormatStyle dateStyle, BTimeFormatStyle timeStyle, 358 const BTimeZone* timeZone) const 359*/ 360 361 362/*! 363 \fn status_t BLocale::FormatTime(BString* string, int*& fieldPositions, 364 int& fieldCount, time_t time, BTimeFormatStyle style) const 365 \brief Fills in \a string with a formatted time for the given 366 \a time and \a style for the locale. 367 368 \param string The string buffer to fill with the formatted time. 369 \param fieldPositions ??? 370 \param fieldCount ??? 371 \param time The time (in seconds since epoch) to format. 372 \param style Specify the long format or the short format. 373 374 \returns A status code. 375 \retval B_OK Everything went fine. 376 \retval B_ERROR Unable to lock the BLocale or an error formatting the time. 377 \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. 378 379 \sa BLocale::FormatDate(BString* string, int*& fieldPositions, 380 int& fieldCount, time_t time, BDateFormatStyle style) const 381*/ 382 383 384/*! 385 \fn status_t BLocale::GetTimeFields(BDateElement*& fields, int& fieldCount, 386 BTimeFormatStyle style) const 387 \brief Get the type of each field in the time format of the locale. 388 389 This function is most often used in combination with FormatTime(). 390 FormatTime() gives you the offset of each field in a formatted string, 391 and GetTimeFields() gives you the type of the field at a given offset. 392 With these informations, you can handle the formatted date string as 393 a list of fields that you can split and alter at will. 394 395 \param fields Pointer to the fields object. 396 \param fieldCount The number of fields. 397 \param style Specify the long format or the short format. 398 399 \returns A status code. 400 \retval B_OK Everything went fine. 401 \retval B_ERROR Unable to lock the BLocale or an error getting the time 402 fields. 403 \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. 404 405 \sa BLocale::GetDateFields(BDateElement*& fields, int& fieldCount, 406 BDateFormatStyle style) const 407*/ 408 409 410/*! 411 \fn ssize_t BLocale::FormatNumber(char* string, size_t maxSize, 412 double value) const 413 \brief Format the \c double \a value as a string and put the result 414 into \a string up to \a maxSize bytes in the current locale. 415 416 \param string The string to put the formatted number into. 417 \param maxSize The maximum of bytes to copy into \a string. 418 \param value The number that you want to get a formatted version of. 419 420 \returns The length of the string created or an error status code in 421 the case of an error. 422 423 \sa BLocale::FormatNumber(char* string, size_t maxSize, 424 int32 value) const 425 \sa ssize_t BLocale::FormatMonetary(char* string, size_t maxSize, 426 double value) const 427*/ 428 429 430/*! 431 \fn status_t BLocale::FormatNumber(BString* string, double value) const 432 \brief \brief Format the \c double \a value as a string and put the result 433 into \a string in the current locale. 434 435 \param string The string to put the formatted number into. 436 \param value The number that you want to get a formatted version of. 437 438 \returns The length of the string created or an error status code in 439 the case of an error. 440 441 \sa BLocale::FormatNumber(BString* string, int32 value) const 442 \sa BLocale::FormatMonetary(BString* string, double value) const 443*/ 444 445 446/*! 447 \fn ssize_t BLocale::FormatNumber(char* string, size_t maxSize, 448 int32 value) const 449 \brief Format the \c int32 \a value as a string and put the result 450 into \a string up to \a maxSize bytes in the current locale. 451 452 \param string The string to put the formatted number into. 453 \param maxSize The maximum of bytes to copy into \a string. 454 \param value The number that you want to get a formatted version of. 455 456 \returns The length of the string created or an error status code in 457 the case of an error. 458 459 \sa BLocale::FormatNumber(char* string, size_t maxSize, 460 double value) const 461 \sa BLocale::FormatMonetary(char* string, size_t maxSize, 462 double value) const 463*/ 464 465 466/*! 467 \fn status_t BLocale::FormatNumber(BString* string, int32 value) const 468 \brief \brief Format the \c int32 \a value as a string and put the result 469 into \a string in the current locale. 470 471 \param string The string to put the formatted number into. 472 \param value The number that you want to get a formatted version of. 473 474 \returns The length of the string created or an error status code in 475 the case of an error. 476 477 \sa BLocale::FormatNumber(BString* string, double value) const 478 \sa BLocale::FormatMonetary(BString* string, double value) const 479*/ 480 481 482/*! 483 \fn ssize_t BLocale::FormatMonetary(char* string, size_t maxSize, 484 double value) const 485 \brief Format the \c double \a value as a monetary string and put the 486 result into \a string up to \a maxSize bytes in the current locale. 487 488 \param string The string to put the monetary formatted number into. 489 \param maxSize The maximum of bytes to copy into \a string. 490 \param value The number that you want to get a monetary formatted version 491 of. 492 493 \returns The length of the string created or an error status code in 494 the case of an error. 495 496 \sa BLocale::FormatNumber(char* string, size_t maxSize, 497 double value) const 498 \sa BLocale::FormatNumber(char* string, size_t maxSize, 499 int32 value) const 500*/ 501 502 503/*! 504 \fn status_t BLocale::FormatMonetary(BString* string, double value) const 505 \brief \brief Format the \c double \a value as a monetary string and put 506 the result into \a string in the current locale. 507 508 \param string The string to put the monetary formatted number into. 509 \param value The number that you want to get a monetary formatted version 510 of. 511 512 \returns The length of the string created or an error status code in 513 the case of an error. 514 515 \sa BLocale::FormatNumber(BString* string, double value) const 516 \sa BLocale::FormatNumber(BString* string, int32 value) const 517*/ 518