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 43095 12 * /trunk/src/kits/locale/Locale.cpp rev 43095 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 If unable to lock the BLocale \a conventions is left untouched. 133 134 \param conventions The formatting convention to set. 135*/ 136 137 138/*! 139 \fn void BLocale::SetCollator(const BCollator& newCollator) 140 \brief Set the collator for this locale. 141 142 If unable to lock the BLocale \a newCollator is left untouched. 143 144 \param newCollator The collator to set. 145*/ 146 147 148/*! 149 \fn void BLocale::SetLanguage(const BLanguage& newLanguage) 150 \brief Set the language for this locale. 151 152 If unable to lock the BLocale \a newLanguage is left untouched. 153 154 \param newLanguage The code of the language to set to locale to. 155*/ 156 157 158/*! 159 \fn ssize_t BLocale::FormatDate(char* string, size_t maxSize, time_t time, 160 BDateFormatStyle style) const 161 \brief Fills in \a string with a formatted date up to \a maxSize bytes for 162 the given \a time and \a style for the locale. 163 164 \param string The string buffer to fill with the formatted date. 165 \param maxSize The size of the buffer. 166 \param time The time (in seconds since epoch) to format 167 \param style Specify the long format (with day name, full 168 month name) or the short format, 08/12/2010 or similar. 169 170 \returns The number of bytes written during the date formatting. 171 \retval B_ERROR Unable to lock the BLocale. 172 \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. 173 \retval B_BAD_VALUE CheckedArrayByteSink overflowed. 174 175 \sa BLocale::FormatDateTime(char* target, size_t maxSize, 176 time_t time, BDateFormatStyle dateStyle, 177 BTimeFormatStyle timeStyle) const 178 \sa BLocale::FormatTime(char* string, size_t maxSize, time_t time, 179 BTimeFormatStyle style) const 180*/ 181 182 183/*! 184 \fn status_t BLocale::FormatDate(BString *string, time_t time, 185 BDateFormatStyle style, const BTimeZone* timeZone) const 186 \brief Fills in \a string with a formatted date for the given 187 \a time, \a style, and \a timeZone for the locale. 188 189 \param string The string buffer to fill with the formatted date. 190 \param time The time (in seconds since epoch) to format 191 \param style Specify the long format (with day name, full 192 month name) or the short format, 08/12/2010 or similar. 193 \param timeZone The time zone. 194 195 \returns A status code. 196 \retval B_OK Everything went fine. 197 \retval B_ERROR Unable to lock the BLocale. 198 \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. 199 200 \sa BLocale::FormatDateTime(BString* target, time_t time, 201 BDateFormatStyle dateStyle, BTimeFormatStyle timeStyle, 202 const BTimeZone* timeZone) const 203 \sa status_t BLocale::FormatTime(BString* string, time_t time, 204 BTimeFormatStyle style, const BTimeZone* timeZone) const 205*/ 206 207 208/*! 209 \fn status_t BLocale::FormatDate(BString* string, int*& fieldPositions, 210 int& fieldCount, time_t time, BDateFormatStyle style) const 211 \brief Fills in \a string with a formatted date for the given 212 \a time and \a style for the locale. 213 214 \param string The string buffer to fill with the formatted date. 215 \param fieldPositions ??? 216 \param fieldCount The number of fields. 217 \param time The time (in seconds since epoch) to format 218 \param style Specify the long format (with day name, full 219 month name) or the short format, 08/12/2010 or similar. 220 221 \returns A status code. 222 \retval B_OK Everything went fine. 223 \retval B_ERROR Unable to lock the BLocale. 224 \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. 225 \retval B_BAD_VALUE An error occurred while performing the date formatting. 226 227 \sa BLocale::FormatTime(BString* string, int*& fieldPositions, 228 int& fieldCount, time_t time, BTimeFormatStyle style) const 229*/ 230 231 232/*! 233 \fn status_t BLocale::GetDateFields(BDateElement*& fields, int& fieldCount, 234 BDateFormatStyle style) const 235 \brief Get the type of each field in the date format of the locale. 236 237 This method is most often used in combination with FormatDate(). 238 FormatDate() gives you the offset of each field in a formatted string, 239 and GetDateFields() gives you the type of the field at a given offset. 240 With these informations, you can handle the formatted date string as 241 a list of fields that you can split and alter at will. 242 243 \param fields Pointer to the fields object. 244 \param fieldCount The number of fields. 245 \param style Specify the long format (with day name, full 246 month name) or the short format, 08/12/2010 or similar. 247 248 \returns A status code. 249 \retval B_OK Everything went fine. 250 \retval B_ERROR Unable to lock the BLocale. 251 \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. 252 \retval B_BAD_VALUE An error occurred while getting the date fields. 253 254 \sa BLocale::GetTimeFields(BDateElement*& fields, int& fieldCount, 255 BTimeFormatStyle style) const 256*/ 257 258 259/*! 260 \fn status_t BLocale::GetStartOfWeek(BWeekday* startOfWeek) const 261 \brief Returns the day used as the start of week in this locale. 262 263 Possible values for \a startOfWeek include: 264 - \c B_WEEKDAY_SUNDAY 265 - \c B_WEEKDAY_MONDAY 266 - \c B_WEEKDAY_TUESDAY 267 - \c B_WEEKDAY_WEDNESDAY 268 - \c B_WEEKDAY_THURSDAY 269 - \c B_WEEKDAY_FRIDAY 270 - \c B_WEEKDAY_SATURDAY 271 272 \returns A status code. 273 \retval B_OK Everything went fine. 274 \retval B_BAD_VALUE \a startOfWeek is \c NULL. 275 \retval B_ERROR Unable to lock the BLocale or another error occurred. 276*/ 277 278 279/*! 280 \fn ssize_t BLocale::FormatDateTime(char* target, size_t maxSize, 281 time_t time, BDateFormatStyle dateStyle, 282 BTimeFormatStyle timeStyle) const 283 \brief Fills in \a string with a formatted datetime up to \a maxSize bytes 284 for the given \a time and \a style for the locale. 285 286 \param target The string buffer to fill with the formatted datetime. 287 \param maxSize The size of the buffer. 288 \param time The time (in seconds since epoch) to format 289 \param dateStyle Specify the long format or the short format of the date. 290 \param timeStyle Specify the long format or the short format of the time. 291 292 \returns The number of bytes written during the datetime formatting. 293 \retval B_ERROR Unable to lock the BLocale. 294 \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. 295 \retval B_BAD_VALUE CheckedArrayByteSink overflowed. 296 297 \sa BLocale::FormatDate(char* string, size_t maxSize, time_t time, 298 BDateFormatStyle style) const 299 \sa BLocale::FormatTime(char* string, size_t maxSize, time_t time, 300 BTimeFormatStyle style) const 301*/ 302 303 304/*! 305 \fn status_t BLocale::FormatDateTime(BString* target, time_t time, 306 BDateFormatStyle dateStyle, BTimeFormatStyle timeStyle, 307 const BTimeZone* timeZone) const 308 \brief Fills in \a string with a formatted datetime for the given 309 \a time, \a timeStyle, and \a timeZone for the locale. 310 311 \param target The string buffer to fill with the formatted date. 312 \param time The time (in seconds since epoch) to format 313 \param dateStyle Specify the long format or the short format of the date. 314 \param timeStyle Specify the long format or the short format of the time. 315 \param timeZone The time zone. 316 317 \returns A status code. 318 \retval B_OK Everything went fine. 319 \retval B_ERROR Unable to lock the BLocale. 320 \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. 321 322 \sa BLocale::FormatDate(BString *string, time_t time, 323 BDateFormatStyle style, const BTimeZone* timeZone) const 324 \sa status_t BLocale::FormatTime(BString* string, time_t time, 325 BTimeFormatStyle style, const BTimeZone* timeZone) const 326*/ 327 328 329/*! 330 \fn ssize_t BLocale::FormatTime(char* string, size_t maxSize, time_t time, 331 BTimeFormatStyle style) const 332 \brief Fills in \a string with a formatted date up to \a maxSize bytes for 333 the given \a time and \a style for the locale. 334 335 \param string The string buffer to fill with the formatted time. 336 \param maxSize The size of the buffer. 337 \param time The time (in seconds since epoch) to format 338 \param style Specify the long format or the short format. 339 340 \returns The number of bytes written during the time formatting. 341 \retval B_ERROR Unable to lock the BLocale. 342 \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. 343 \retval B_BAD_VALUE CheckedArrayByteSink overflowed. 344 345 \sa BLocale::FormatDate(char* string, size_t maxSize, time_t time, 346 BDateFormatStyle style) const 347 \sa BLocale::FormatDateTime(char* target, size_t maxSize, 348 time_t time, BDateFormatStyle dateStyle, 349 BTimeFormatStyle timeStyle) const 350*/ 351 352 353/*! 354 \fn status_t BLocale::FormatTime(BString* string, time_t time, 355 BTimeFormatStyle style, const BTimeZone* timeZone) const 356 \brief Fills in \a string with a formatted time for the given 357 \a time, \a style, and \a timeZone for the locale. 358 359 \param string The string buffer to fill with the formatted date. 360 \param time The time (in seconds since epoch) to format 361 \param style Specify the long format or the short format. 362 \param timeZone The time zone. 363 364 \returns A status code. 365 \retval B_OK Everything went fine. 366 \retval B_ERROR Unable to lock the BLocale. 367 \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. 368 369 \sa BLocale::FormatDate(BString *string, time_t time, 370 BDateFormatStyle style, const BTimeZone* timeZone) const 371 \sa BLocale::FormatDateTime(BString* target, time_t time, 372 BDateFormatStyle dateStyle, BTimeFormatStyle timeStyle, 373 const BTimeZone* timeZone) const 374*/ 375 376 377/*! 378 \fn status_t BLocale::FormatTime(BString* string, int*& fieldPositions, 379 int& fieldCount, time_t time, BTimeFormatStyle style) const 380 \brief Fills in \a string with a formatted time for the given 381 \a time and \a style for the locale. 382 383 \param string The string buffer to fill with the formatted time. 384 \param fieldPositions ??? 385 \param fieldCount ??? 386 \param time The time (in seconds since epoch) to format. 387 \param style Specify the long format or the short format. 388 389 \returns A status code. 390 \retval B_OK Everything went fine. 391 \retval B_ERROR Unable to lock the BLocale. 392 \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. 393 \retval B_BAD_VALUE An error occurred during time formatting. 394 395 \sa BLocale::FormatDate(BString* string, int*& fieldPositions, 396 int& fieldCount, time_t time, BDateFormatStyle style) const 397*/ 398 399 400/*! 401 \fn status_t BLocale::GetTimeFields(BDateElement*& fields, int& fieldCount, 402 BTimeFormatStyle style) const 403 \brief Get the type of each field in the time format of the locale. 404 405 This method is used most often in combination with FormatTime(). 406 FormatTime() gives you the offset of each field in a formatted string, 407 and GetTimeFields() gives you the type of the field at a given offset. 408 With this information you can handle the formatted date string as 409 a list of fields that you can split and alter at will. 410 411 \param fields Pointer to the fields object. 412 \param fieldCount The number of fields. 413 \param style Specify the long format or the short format. 414 415 \returns A status code. 416 \retval B_OK Everything went fine. 417 \retval B_ERROR Unable to lock the BLocale. 418 \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. 419 \retval B_BAD_VALUE An error occurred while getting the time fields. 420 421 \sa BLocale::GetDateFields(BDateElement*& fields, int& fieldCount, 422 BDateFormatStyle style) const 423*/ 424 425 426/*! 427 \fn ssize_t BLocale::FormatNumber(char* string, size_t maxSize, 428 double value) const 429 \brief Format the \c double \a value as a string and put the result 430 into \a string up to \a maxSize bytes in the current locale. 431 432 \param string The string to put the formatted number into. 433 \param maxSize The maximum of bytes to copy into \a string. 434 \param value The number that you want to get a formatted version of. 435 436 \returns The length of the string created or an error status code. 437 \retval B_ERROR Unable to lock the BLocale. 438 \retval B_NO_MEMORY Ran out of memory while creating the NumberFormat 439 object. 440 \retval B_BAD_VALUE An error occurred while formatting the number. 441 442 \sa BLocale::FormatNumber(char* string, size_t maxSize, 443 int32 value) const 444 \sa ssize_t BLocale::FormatMonetary(char* string, size_t maxSize, 445 double value) const 446*/ 447 448 449/*! 450 \fn status_t BLocale::FormatNumber(BString* string, double value) const 451 \brief \brief Format the \c double \a value as a string and put the 452 result into \a string in the current locale. 453 454 \param string The string to put the formatted number into. 455 \param value The number that you want to get a formatted version of. 456 457 \returns A status code. 458 \retval B_OK Everything went fine. 459 \retval B_ERROR Unable to lock the BLocale. 460 \retval B_NO_MEMORY Ran out of memory while creating the NumberFormat 461 object. 462 \retval B_BAD_VALUE An error occurred while formatting the number. 463 464 \sa BLocale::FormatNumber(BString* string, int32 value) const 465 \sa BLocale::FormatMonetary(BString* string, double value) const 466*/ 467 468 469/*! 470 \fn ssize_t BLocale::FormatNumber(char* string, size_t maxSize, 471 int32 value) const 472 \brief Format the \c int32 \a value as a string and put the result 473 into \a string up to \a maxSize bytes in the current locale. 474 475 \param string The string to put the formatted number into. 476 \param maxSize The maximum of bytes to copy into \a string. 477 \param value The number that you want to get a formatted version of. 478 479 \returns The length of the string created or an error status code. 480 \retval B_ERROR Unable to lock the BLocale. 481 \retval B_NO_MEMORY Ran out of memory while creating the NumberFormat 482 object. 483 \retval B_BAD_VALUE An error occurred while formatting the number. 484 485 \sa BLocale::FormatNumber(char* string, size_t maxSize, 486 double value) const 487 \sa BLocale::FormatMonetary(char* string, size_t maxSize, 488 double value) const 489*/ 490 491 492/*! 493 \fn status_t BLocale::FormatNumber(BString* string, int32 value) const 494 \brief \brief Format the \c int32 \a value as a string and put the result 495 into \a string in the current locale. 496 497 \param string The string to put the formatted number into. 498 \param value The number that you want to get a formatted version of. 499 500 \returns A status code. 501 \retval B_OK Everything went fine. 502 \retval B_ERROR Unable to lock the BLocale. 503 \retval B_NO_MEMORY Ran out of memory while creating the NumberFormat 504 object. 505 \retval B_BAD_VALUE An error occurred while formatting the number. 506 507 \sa BLocale::FormatNumber(BString* string, double value) const 508 \sa BLocale::FormatMonetary(BString* string, double value) const 509*/ 510 511 512/*! 513 \fn ssize_t BLocale::FormatMonetary(char* string, size_t maxSize, 514 double value) const 515 \brief Format the \c double \a value as a monetary string and put the 516 result into \a string up to \a maxSize bytes in the current locale. 517 518 \param string The \a string to put the monetary formatted number into. 519 \param maxSize The maximum of bytes to copy into \a string. 520 \param value The number to format as a monetary \a value. 521 522 \returns The length of the string created or an error status code. 523 \retval B_ERROR Unable to lock the BLocale. 524 \retval B_NO_MEMORY Ran out of memory while creating the NumberFormat 525 object. 526 \retval B_BAD_VALUE An error occurred while formatting the number. 527 528 \sa BLocale::FormatNumber(char* string, size_t maxSize, double value) const 529 \sa BLocale::FormatNumber(char* string, size_t maxSize, int32 value) const 530*/ 531 532 533/*! 534 \fn status_t BLocale::FormatMonetary(BString* string, double value) const 535 \brief \brief Format the \c double \a value as a monetary string and put 536 the result into \a string in the current locale. 537 538 \param string The \a string to put the monetary formatted number into. 539 \param value The number to format as a monetary \a value. 540 541 \returns A status code. 542 \retval B_OK Everything went fine. 543 \retval B_ERROR Unable to lock the BLocale. 544 \retval B_NO_MEMORY Ran out of memory while creating the NumberFormat 545 object. 546 \retval B_BAD_VALUE An error occurred while formatting the number. 547 548 \sa BLocale::FormatNumber(BString* string, double value) const 549 \sa BLocale::FormatNumber(BString* string, int32 value) const 550*/ 551