/*]  Copyright (c) 2009-2011, Charles McGarvey  [*****************************
**]  All rights reserved.
*
* Distributable under the terms and conditions of the 2-clause BSD license;
* see the file COPYING for a complete text of the license.
*
*****************************************************************************/

#ifndef _MOOF_STRING_HH_
#define _MOOF_STRING_HH_

#include <string>

#include <boost/noncopyable.hpp>


/**
 * \file string.hh
 * Functions and classes related to string manipulation.
 */

namespace moof {


using std::string;
using std::wstring;

/**
 * Convert a multi-byte (UTF-8) string to a wide string.
 * \param multi The multi-byte string to convert.
 * \return The equivalent wide string.
 */
wstring multi_to_wide(const string& multi);

/**
 * Convert a wide string to a multi-byte (UTF-8) string.
 * \param wide The wide string to convert.
 * \return The equivalent multi-byte string.
 */
string wide_to_multi(const wstring& wide);


/**
 * Class exposing the pattern-matching and substitution methods used in
 * Lua.
 */
class pattern : public boost::noncopyable
{
public:

	/**
	 * Construct a pattern object.
	 */
	pattern() {}

	/**
	 * Construct a pattern object with a pattern.
	 * \param pattern The pattern.
	 */
	pattern(const std::string& pattern);

	/**
	 * Construct a pattern object with a pattern and source to match.
	 * \param pattern The pattern.
	 * \param source The source string.
	 */
	pattern(const std::string& pattern, const std::string& source);

	/**
	 * Deconstruct the pattern.
	 */
	~pattern();

	/**
	 * Get the pattern pattern.
	 */
	std::string string() const;

	/**
	 * Set the pattern string.
	 */
	void string(const std::string& pattern);

	/**
	 * Match a string against the pattern iteratively.
	 * \param source The source string.
	 */
	void match(const std::string& source);

	/**
	 * Get the next match.  If the pattern contains captures, this version
	 * will only get the first capture.
	 * \param match Reference to a string to be assigned the match.
	 * \return True if there was a match to get, false otherwise.
	 */
	bool get(std::string& match);

	/**
	 * Get the next match.  Use this version if the pattern contains more
	 * than one capture to get all of the captures.
	 * \param captures Reference to a vector of strings to hold the result.
	 * \return True if there was a match to get, false otherwise.
	 */
	bool get(std::vector<std::string>& captures);

	/**
	 * Match a string against a pattern all at one time.
	 * \param pattern The pattern.
	 * \param source The source string.
	 * \param position The index of the first character of source to match.
	 * \return The match.
	 */
	static std::string
	match(const std::string& pattern, const std::string& source,
			int position = 0)
	{
		std::string match;
		pattern::match(match, pattern, source, position);
		return match;
	}

	/**
	 * Match a string against a pattern all at one time.
	 * \param match A reference to a string to be assigned the match.
	 * \param pattern The pattern.
	 * \param source The source string.
	 * \param position The index of the first character of source to match.
	 * \return True if a match was made, false otherwise.
	 */
	static bool match(std::string& match, const std::string& pattern,
			const std::string& source, int position = 0);

	/**
	 * Match a string against a pattern all at one time.  If the pattern
	 * contains captures, the resulting vector will contain all of the
	 * captures.
	 * \param captures A reference to a vector of strings to contain the
	 * result.
	 * \param pattern The pattern.
	 * \param source The source string.
	 * \param position The index of the first character of source to match.
	 * \return True if a match was made, false otherwise.
	 */
	static bool match(std::vector<std::string>& captures, const std::string& pattern,
			const std::string& source, int position = 0);

	/**
	 * Substitute a string using a pattern and replacement string.
	 * \param pattern The pattern.
	 * \param source The source string.
	 * \param replacement The replacement string; may also contain
	 * references to captures.
	 * \return The string with any substitutions made.
	 */
	static std::string sub(const std::string& pattern,
			const std::string& source, const std::string& replacement)
	{
		std::string substitution;
		pattern::sub(substitution, pattern, source, replacement);
		return substitution;
	}

	/**
	 * Substitute a string using a pattern and replacement string.
	 * \param substitution A reference to a string to contain the result.
	 * \param pattern The pattern.
	 * \param source The source string.
	 * \param replacement The replacement string; may also contain
	 * references to captures.
	 * \return The number of substitutions made.
	 */
	static int sub(std::string& substitution, const std::string& pattern,
			const std::string& source, const std::string& replacement);
};


} // namespace moof

#endif // _MOOF_STRING_HH_