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