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