CLASS TEMPLAT(3)

NAME
boost::date_time::period_formatter - Not a facet, but a class used to specify and control period formats.

SYNOPSIS

// In header: <boost/date_time/period_formatter.hpp>
template<typename CharT,
         typename OutItrT = std::ostreambuf_iterator<CharT, std::char_traits<CharT> > >
class period_formatter {
public:
  // types
  typedef std::basic_string< CharT >                     string_type;
  typedef CharT                                          char_type;
  typedef std::basic_string< char_type >::const_iterator const_itr_type;
  typedef std::vector< std::basic_string< CharT > >      collection_type;
  enum range_display_options { AS_OPEN_RANGE, AS_CLOSED_RANGE };
  // construct/copy/destruct
  period_formatter(range_display_options = AS_CLOSED_RANGE,
                   const char_type *const = default_period_separator,
                   const char_type *const = default_period_start_delimeter,
                   const char_type *const = default_period_open_range_end_delimeter,
                   const char_type *const = default_period_closed_range_end_delimeter);
  // public member functions
  OutItrT put_period_separator(OutItrT &) const;
  OutItrT put_period_start_delimeter(OutItrT &) const;
  OutItrT put_period_end_delimeter(OutItrT &) const;
  range_display_options range_option() const;
  void range_option(range_display_options) const;
  void delimiter_strings(const string_type &, const string_type &,
                         const string_type &, const string_type &);
  template<typename period_type, typename facet_type>
    OutItrT put_period(OutItrT, std::ios_base &, char_type,
                       const period_type &, const facet_type &) const;
  static const char_type default_period_separator;
  static const char_type default_period_start_delimeter;
  static const char_type default_period_open_range_end_delimeter;
  static const char_type default_period_closed_range_end_delimeter;
};

DESCRIPTION

Provides settings for the following:

    &#8226; period_separator -- default '/'

    &#8226; period_open_start_delimeter -- default '['

    &#8226; period_open_range_end_delimeter -- default ')'

    &#8226; period_closed_range_end_delimeter -- default ']'

    &#8226; display_as_open_range, display_as_closed_range -- default closed_range

Thus the default formatting for a period is as follows:

      [period.start()/period.last()]
       *

So for a typical date_period this would be

      [2004-Jan-04/2004-Feb-01]
       *

where the date formatting is controlled by the date facet

  period_formatter public construct/copy/destruct

    1.

    period_formatter(range_display_options range_option_in = AS_CLOSED_RANGE,
                     const char_type *const period_separator = default_period_separator,
                     const char_type *const period_start_delimeter = default_period_start_delimeter,
                     const char_type *const period_open_range_end_delimeter = default_period_open_range_end_delimeter,
                     const char_type *const period_closed_range_end_delimeter = default_period_closed_range_end_delimeter);
    Constructor that sets up period formatter options -- default should suffice most cases. .RE

  period_formatter public member functions

    1.

    OutItrT put_period_separator(OutItrT & oitr) const;
    Puts the characters between period elements into stream -- default is /. .RE

        2.

        OutItrT put_period_start_delimeter(OutItrT & oitr) const;
        Puts the period start characters into stream -- default is [. .RE

            3.

            OutItrT put_period_end_delimeter(OutItrT & oitr) const;
            Puts the period end characters into stream as controled by open/closed range setting. .RE

                4.

                range_display_options range_option() const;

                5.

                void range_option(range_display_options option) const;
                Reset the range_option control. .RE

                    6.

                    void delimiter_strings(const string_type & separator,
                                           const string_type & start_delim,
                                           const string_type & open_end_delim,
                                           const string_type & closed_end_delim);

                    7.

                    template<typename period_type, typename facet_type>
                      OutItrT put_period(OutItrT next, std::ios_base & a_ios, char_type a_fill,
                                         const period_type & p, const facet_type & facet) const;

                    Generic code to output a period -- no matter the period type. This generic code will output any period using a facet to to output the 'elements'. For example, in the case of a date_period the elements will be instances of a date which will be formatted according the to setup in the passed facet parameter.

                    The steps for formatting a period are always the same:

                        &#8226; put the start delimiter

                        &#8226; put start element

                        &#8226; put the separator

                        &#8226; put either last or end element depending on range settings

                        &#8226; put end delimeter depending on range settings

                        Thus for a typical date period the result might look like this:

                                [March 01, 2004/June 07, 2004]   <-- closed range
                                [March 01, 2004/June 08, 2004)   <-- open range
                                 *