haiku/docs/user/locale/Locale.dox

/*
 * Copyright 2011-2014 Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Axel Dörfler, axeld@pinc-software.de.
 *		John Scipione, jscipione@gmail.com
 *		Oliver Tappe, zooey@hirschkaefer.de.
 *
 * Corresponds to:
 *		headers/os/locale/Locale.h	hrev48439
 *		src/kits/locale/Locale.cpp	hrev48439
 */


/*!
	\file Locale.h
	\ingroup locale
	\ingroup libbe
	\brief Provides the BLocale class, the base class of the Locale Kit.
*/


/*!
	\class BLocale
	\ingroup locale
	\ingroup libbe
	\brief Class for representing a locale and its settings.

	A locale is defined by the combination of a country and a language.
	Using these two informations, it is possible to determine the format
	to use for date, time, and number formatting. The BLocale class also
	provide collators, which allows you to sort a list of strings properly
	depending on a set of rules about accented chars and other special
	cases that vary over the different locales.

	BLocale is also the class to use when you want to perform formatting
	or parsing of dates, times, and numbers, in the natural language of
	the user.

	\since Haiku R1
*/


/*!
	\fn BLocale::BLocale(const BLanguage* language,
		const BFormattingConventions* conventions)
	\brief Initializes a BLocale object corresponding to the passed in
	       \a language and \a conventions.

	\since Haiku R1
*/


/*!
	\fn BLocale::BLocale(const BLocale& other)
	\brief Initializes a BLocale object as a copy of \a other.

	\param other The BLocale object to initialize from.

	\since Haiku R1
*/


/*!
	status_t BLocale::GetCollator(BCollator* collator) const
	\brief Gets the collator associated to this locale.

	Returns the collator in use for this locale, allowing you to use it
	to sort a set of strings.

	\since Haiku R1
*/


/*!
	\fn BLocale& BLocale::operator=(const BLocale& other)
	\brief Initializes a BLocale object as a copy of \a other by overloading
	       the = operator.

	\param other The BLocale object to initialize from.

	\since Haiku R1
*/


/*!
	\fn BLocale::~BLocale()
	\brief Destructor method.

	\since Haiku R1
*/


/*!
	\fn status_t BLocale::GetCollator(BCollator* collator) const
	\brief Sets \a collator object to the default collator for the BLocale.

	\param collator A pointer to a BCollator object to fill out.

	\returns A status code.
	\retval B_OK Everything went well.
	\retval B_BAD_VALUE \c NULL \a collator object passed in.
	\retval B_ERROR Unable to lock the BLocale. 

	\since Haiku R1
*/


/*!
	\fn status_t BLocale::GetLanguage(BLanguage* language) const
	\brief Sets \a language object to the default language for the BLocale.

	\param language A pointer to a BLanguage object to fill out.

	\returns A status code.
	\retval B_OK Everything went well.
	\retval B_BAD_VALUE \c NULL \a language object passed in.
	\retval B_ERROR Unable to lock the BLocale. 

	\since Haiku R1
*/


/*!
	\fn status_t BLocale::GetFormattingConventions(
		BFormattingConventions* conventions) const
	\brief Fills out \a conventions with the default formatting conventions
	       for the BLocale.

	\param conventions A pointer to a BFormattingConventions object to fill
	       out.

	\returns A status code.
	\retval B_OK Everything went well.
	\retval B_BAD_VALUE \c NULL \a conventions object passed in.
	\retval B_ERROR Unable to lock the BLocale.

	\since Haiku R1
*/


/*!
	\fn const char* BLocale::GetString(uint32 id) const
	\brief Gets the language string for the locale.

	\param id The locale \a id to get the language of.

	\internal Assumes a certain order of the string bases.

	\returns A blank string in the case of an error or the string "UTF-8"
	         if there is \a id is set to \a B_CODESET.

	\since Haiku R1
*/


/*!
	\fn void BLocale::SetFormattingConventions(
		const BFormattingConventions& conventions)
	\brief Sets the formatting convention for this locale.

	If unable to lock the BLocale \a conventions is left untouched.

	\param conventions The formatting convention to set.

	\since Haiku R1
*/


/*!
	\fn void BLocale::SetCollator(const BCollator& newCollator)
	\brief Set the collator for this locale.

	If unable to lock the BLocale \a newCollator is left untouched.

	\param newCollator The collator to set.

	\since Haiku R1
*/


/*!
	\fn void BLocale::SetLanguage(const BLanguage& newLanguage)
	\brief Set the language for this locale.

	If unable to lock the BLocale \a newLanguage is left untouched.

	\param newLanguage The code of the language to set to locale to.

	\since Haiku R1
*/