docs/user/locale/Locale.dox

   1 /*
   2  * Copyright 2011-2014 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      hrev48439
  12  *              src/kits/locale/Locale.cpp      hrev48439
  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 */