format.h

C++ class libraries for network-centric, portable applications, integrated perfectly with the C++ St

//
// Format.h
//
// $Id: //poco/1.2/Foundation/include/Poco/Format.h#1 $
//
// Library: Foundation
// Package: Core
// Module:  Format
//
// Definition of the format freestanding function.
//
// Copyright (c) 2006, Applied Informatics Software Engineering GmbH.
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions
// are met:
//
// 1. Redistributions of source code must retain the above copyright
//    notice, this list of conditions and the following disclaimer.
//
// 2. Redistributions in binary form must reproduce the above copyright
//    notice, this list of conditions and the following disclaimer in the
//    documentation and/or other materials provided with the distribution.
//
// 3. Redistributions in any form must be accompanied by information on
//    how to obtain complete source code for this software and any
//    accompanying software that uses this software.  The source code
//    must either be included in the distribution or be available for no
//    more than the cost of distribution plus a nominal fee, and must be
//    freely redistributable under reasonable conditions.  For an
//    executable file, complete source code means the source code for all
//    modules it contains.  It does not include source code for modules or
//    files that typically accompany the major components of the operating
//    system on which the executable file runs.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
// FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
// COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
// INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
// BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
// LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
// ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
// POSSIBILITY OF SUCH DAMAGE.
//


#ifndef Foundation_Format_INCLUDED
#define Foundation_Format_INCLUDED


#include "Poco/Foundation.h"
#include "Poco/Any.h"
#include <vector>


namespace Poco {


std::string Foundation_API format(const std::string& fmt, const Any& value);
	/// This function implements sprintf-style formatting in a typesafe way.
	/// Various variants of the function are available, supporting a
	/// different number of arguments (up to six).
	///
	/// The formatting is controlled by the format string in fmt.
	/// Format strings are quite similar to those of the printf() function, but
	/// there are some minor differences.
	///
	/// The format string can consist of any sequence of characters; certain
	/// characters have a special meaning. Characters without a special meaning
	/// are copied verbatim to the result. A percent sign (%) marks the beginning
	/// of a format specification. Format specifications have the following syntax:
	///
	///   %[<flags>][<width>][.<precision>][<modifier>]<type>
	///
	/// Flags, width, precision and prefix are optional. The only required part of
	/// the format specification, apart from the percent sign, is the type.
	///
	/// Following are valid type specifications and their meaning:
	///
	///   * c character
	///   * d signed decimal integer
	///   * i signed decimal integer
	///   * o unsigned octal integer
	///   * u unsigned decimal integer
	///   * x unsigned hexadecimal integer (lower case)
	///   * X unsigned hexadecimal integer (upper case)
	///   * e signed floating-point value in the form [-]d.dddde[<sign>]dd[d]
	///   * E signed floating-point value in the form [-]d.ddddE[<sign>]dd[d]
	///   * f signed floating-point value in the form [-]dddd.dddd
	///   * s std::string
	///
	/// The following flags are supported:
	///
	///   * - left align the result within the given field width
	///   * + prefix the output value with a sign (+ or