xref: /haiku/docs/user/locale/DateFormat.dox (revision 71f6259a0f888bf60251216784d521150e40255e)

/*
 * Copyright 2011-2014 Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Adrien Destugues, pulkomandy@pulkomandy.ath.cx
 *		John Scipione, jscipione@gmail.com
 *
 * Corresponds to:
 *		headers/os/locale/DateFormat.h	hrev48439
 *		src/kits/locale/DateFormat.cpp	hrev48439
 */


/*!
	\file DateFormat.h
	\ingroup locale
	\ingroup libbe
	\brief Contains BDateFormat class, a date formatter and parser.
*/


/*!
	\class BDateFormat
	\ingroup locale
	\ingroup libbe
	\brief Formatter for dates.

	\since Haiku R1
*/


/*!
	\fn BDateFormat::BDateFormat(const BLocale* locale)
	\brief Locale constructor.

	\param locale The locale to use, can be \c NULL for the default locale.

	\since Haiku R1
*/


/*!
	\fn BDateFormat::BDateFormat(const BLanguage& language,
		const BFormattingConventions& format);
	\brief Language and formatting convention constructor.

	\param language The \a language to use.
	\param format The formatting convention to use.

	\since Haiku R1
*/


/*!
	\fn BDateFormat::BDateFormat(const BDateFormat& other)
	\brief Copy Constructor.

	\param other The BDateFormat object to copy from.

	\since Haiku R1
*/


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

	\since Haiku R1
*/


/*!
	\fn ssize_t BDateFormat::Format(char* string, const size_t maxSize,
		const time_t time, const BDateFormatStyle style) const
	\brief Fills in \a string with a formatted date up to \a maxSize bytes for
	       the given \a time and \a style for the locale.

	\param string The string buffer to fill with the formatted date.
	\param maxSize The size of the buffer.
	\param time The time (in seconds since epoch) to format
	\param style Specify the long format (with day name, full
	       month name) or the short format, 08/12/2010 or similar.

	\returns The number of bytes written during the date formatting.
	\retval B_ERROR Unable to lock the BLocale.
	\retval B_NO_MEMORY Ran out of memory while creating the object.
	\retval B_BAD_VALUE There was not enough space to store the result.

	\since Haiku R1
*/


/*!
	\fn status_t BDateFormat::Format(BString& string, const time_t time,
		const BDateFormatStyle style, const BTimeZone* timeZone) const
	\brief Fills in \a string with a formatted date for the given
	       \a time, \a style, and \a timeZone for the locale.

	\param string The string buffer to fill with the formatted date.
	\param time The time (in seconds since epoch) to format
	\param style Specify the long format (with day name, full
		month name) or the short format, 08/12/2010 or similar.
	\param timeZone Specifies the time zone to use, if \c NULL, use the
	       system default time zone (usually UTC).

	\returns A status code.
	\retval B_OK Everything went fine.
	\retval B_ERROR Unable to lock the BLocale.
	\retval B_NO_MEMORY Ran out of memory while creating the object.

	\since Haiku R1
*/


/*!
	\fn status_t BDateFormat::Format(BString& string,
		int*& fieldPositions, int& fieldCount, const time_t time,
		const BDateFormatStyle style) const
	\brief Fills in \a string with a custom formatted date according to the
	       given parameters for the locale and fills out an array of
	       \a fieldPositions which must be freed by the caller and a
	       \a fieldCount which contains the number of positions.

	The positions are offsets in the string at which each element of the date
	(day, month, year, etc) and the separator starting positions. These
	can be used, for example, to split the string into parts to use in a
	locale-aware set of BMenuFields to edit the date in the local format.

	\param string The string buffer to fill with the formatted date.
	\param fieldPositions An array of date field positions to be filled out.
	\param fieldCount The number of \a fields in \a fieldPositions to be
	       filled out.
	\param time The time (in seconds since epoch) to format
	\param style Specify the long format (with day name, full
		month name) or the short format, 08/12/2010 or similar.

	\returns A status code.
	\retval B_OK Everything went fine.
	\retval B_ERROR Unable to lock the BLocale.
	\retval B_NO_MEMORY Ran out of memory while creating the \a string buffer
	        or \a fieldPositions array.
	\retval B_BAD_VALUE There was not enough space to store the result.

	\since Haiku R1
*/


/*!
	\fn status_t BDateFormat::GetFields(BDateElement*& fields, int& fieldCount,
		BDateFormatStyle style) const
	\brief Get the type of each field in the date format of the locale.

	This method is most often used in combination with the version of Format()
	that takes a fieldPositions parameter. Format() gives you the offset of
	each field in a formatted string, and GetFields() gives you the type of
	the field at a given offset. With these informations, you can handle the
	formatted date string as a list of fields that you can split and alter at
	will.

	\param fields Pointer to the array of BDateElement objects.
	\param fieldCount The number of fields in \a fields.
	\param style Specify the long format (with day name, full month name)
	       or the short format, "08/12/2010" or similar.

	\returns A status code.
	\retval B_OK Everything went fine.
	\retval B_ERROR Unable to lock the BLocale.
	\retval B_NO_MEMORY Ran out of memory while creating the object.
	\retval B_BAD_VALUE Bad or invalid \a fields data.

	\sa BDateFormat::GetFields(BDateElement*&, int&, BTimeFormatStyle) const
	\sa BDateFormat::Format(BString&, int*&, int&, const time_t,
		const BDateFormatStyle) const

	\since Haiku R1
*/


/*!
	\fn status_t BDateFormat::GetStartOfWeek(BWeekday* startOfWeek) const
	\brief Returns the day used as the start of week in this locale.

	Possible values for \a startOfWeek include:
		- \c B_WEEKDAY_SUNDAY
		- \c B_WEEKDAY_MONDAY
		- \c B_WEEKDAY_TUESDAY
		- \c B_WEEKDAY_WEDNESDAY
		- \c B_WEEKDAY_THURSDAY
		- \c B_WEEKDAY_FRIDAY
		- \c B_WEEKDAY_SATURDAY

	\returns A status code.
	\retval B_OK Everything went fine.
	\retval B_BAD_VALUE \a startOfWeek is \c NULL.
	\retval B_ERROR Unable to lock the BLocale or another error occurred.

	\since Haiku R1
*/