ncbistr.hpp

ncbi源码

/*
 * ===========================================================================
 * PRODUCTION $Log: ncbistr.hpp,v $
 * PRODUCTION Revision 1000.6  2004/06/01 19:08:11  gouriano
 * PRODUCTION PRODUCTION: UPGRADED [GCC34_MSVC7] Dev-tree R1.56
 * PRODUCTION
 * ===========================================================================
 */

#ifndef CORELIB___NCBISTR__HPP
#define CORELIB___NCBISTR__HPP

/*  $Id: ncbistr.hpp,v 1000.6 2004/06/01 19:08:11 gouriano Exp $
 * ===========================================================================
 *
 *                            PUBLIC DOMAIN NOTICE
 *               National Center for Biotechnology Information
 *
 *  This software/database is a "United States Government Work" under the
 *  terms of the United States Copyright Act.  It was written as part of
 *  the author's official duties as a United States Government employee and
 *  thus cannot be copyrighted.  This software/database is freely available
 *  to the public for use. The National Library of Medicine and the U.S.
 *  Government have not placed any restriction on its use or reproduction.
 *
 *  Although all reasonable efforts have been taken to ensure the accuracy
 *  and reliability of the software and data, the NLM and the U.S.
 *  Government do not and cannot warrant the performance or results that
 *  may be obtained by using this software or data. The NLM and the U.S.
 *  Government disclaim all warranties, express or implied, including
 *  warranties of performance, merchantability or fitness for any particular
 *  purpose.
 *
 *  Please cite the author in any work or product based on this material.
 *
 * ===========================================================================
 *
 * Authors:  Eugene Vasilchenko, Denis Vakatov
 *
 *
 */

/// @file ncbistr.hpp
/// The NCBI C++ standard methods for dealing with std::string


#include <corelib/ncbitype.h>
#include <corelib/ncbiexpt.hpp>
#include <corelib/ncbistl.hpp>
#include <string.h>
#include <ctype.h>
#include <time.h>
#include <stdarg.h>
#include <string>
#include <list>
#include <vector>



BEGIN_NCBI_SCOPE

/** @addtogroup String
 *
 * @{
 */

/// Empty "C" string (points to a '\0').
NCBI_XNCBI_EXPORT extern const char *const kEmptyCStr;
#define NcbiEmptyCStr NCBI_NS_NCBI::kEmptyCStr


/// Empty "C++" string.
#ifndef NCBI_OS_MSWIN
class NCBI_XNCBI_EXPORT CNcbiEmptyString
{
public:
    /// Get string.
    static const string& Get(void);
private:
    /// Helper method to initialize private data member and return
    /// null string.
    static const string& FirstGet(void);
    static const string* m_Str;     ///< Null string pointer.
};
#else  // NCBI_OS_MSWIN 
class CNcbiEmptyString
{
public:
    /// Get string.
    static const string& Get(void)
    {
        static string empty_str;
        return empty_str;
    }
};
#endif // NCBI_OS_MSWIN
/// Empty string definition.
#define NcbiEmptyString NCBI_NS_NCBI::CNcbiEmptyString::Get()

/// Empty string definition.
#define kEmptyStr       NcbiEmptyString


// SIZE_TYPE and NPOS

/// Define size type.
typedef NCBI_NS_STD::string::size_type SIZE_TYPE;

/// Define NPOS constant as the special value "std::string::npos" which is
/// returned when a substring search fails, or to indicate an unspecified
/// string position.
static const SIZE_TYPE NPOS = NCBI_NS_STD::string::npos;



/////////////////////////////////////////////////////////////////////////////
///
/// NStr --
///
/// Encapuslates class-wide string processing functions.

class NCBI_XNCBI_EXPORT NStr
{
public:
    /// Convert string to numeric value.
    ///
    /// @param str
    ///   String containing digits.
    /// @return
    ///   - Convert "str" to a (non-negative) "int" value and return
    ///     this value.
    ///   - -1 if "str" contains any symbols other than [0-9], or
    ///     if it represents a number that does not fit into "int".
    static int StringToNumeric(const string& str);

    /// Whether to prohibit trailing symbols (any symbol but '\0')
    /// in the StringToXxx() conversion functions below.
    enum ECheckEndPtr {
        eCheck_Need,   ///< Check is necessary
        eCheck_Skip    ///< Skip this check
    };

    /// Convert string to int.
    ///
    /// @param str
    ///   String to be converted.
    /// @param base
    ///   Numeric base of the number symbols (default = 10).
    /// @param check
    ///   Whether trailing symbols (other than '\0') are permitted - default
    ///   is eCheck_Needed which means that if there are trailing symbols
    ///   after the number, an exception will be thrown. If the value is
    ///   eCheck_Skip, the string can have trailing symbols after the number.
    static int StringToInt(const string& str, int base = 10,
                           ECheckEndPtr check = eCheck_Need);

    /// Convert string to unsigned int.
    ///
    /// @param str
    ///   String to be converted.
    /// @param base
    ///   Numeric base of the number symbols (default = 10).
    /// @param check
    ///   Whether trailing symbols (other than '\0') are permitted - default
    ///   is eCheck_Needed which means that if there are trailing symbols
    ///   after the number, an exception will be thrown. If the value is
    ///   eCheck_Skip, the string can have trailing symbols after the number.
    static unsigned int StringToUInt(const string& str, int base = 10,
                                     ECheckEndPtr check = eCheck_Need);

    /// Convert string to long.
    ///
    /// @param str
    ///   String to be converted.
    /// @param base
    ///   Numeric base of the number symbols (default = 10).
    /// @param check
    ///   Whether trailing symbols (other than '\0') are permitted - default
    ///   is eCheck_Needed which means that if there are trailing symbols
    ///   after the number, an exception will be thrown. If the value is
    ///   eCheck_Skip, the string can have trailing symbols after the number.
    static long StringToLong(const string& str, int base = 10,
                             ECheckEndPtr check = eCheck_Need);

    /// Convert string to unsigned long.
    ///
    /// @param str
    ///   String to be converted.
    /// @param base
    ///   Numeric base of the number symbols (default = 10).
    /// @param check
    ///   Whether trailing symbols (other than '\0') are permitted - default
    ///   is eCheck_Needed which means that if there are trailing symbols
    ///   after the number, an exception will be thrown. If the value is
    ///   eCheck_Skip, the string can have trailing symbols after the number.
    static unsigned long StringToULong(const string& str, int base = 10,
                                       ECheckEndPtr check = eCheck_Need);

    /// Convert string to double.
    ///
    /// @param str
    ///   String to be converted.
    /// @param check
    ///   Whether trailing symbols (other than '\0') are permitted - default
    ///   is eCheck_Needed which means that if there are trailing symbols
    ///   after the number, an exception will be thrown. If the value is
    ///   eCheck_Skip, the string can have trailing symbols after the number.
    static double StringToDouble(const string& str,
                                 ECheckEndPtr check = eCheck_Need);

    /// Convert string to Int8.
    ///
    /// @param str
    ///   String to be converted.
    /// @return
    ///   Converted Int8 value.
    static Int8 StringToInt8(const string& str);

    /// Convert string to Uint8.
    ///
    /// @param str
    ///   String to be converted.
    /// @param base
    ///   Radix base. Default is 10. Other values can be 2, 8, and 16.
    /// @return
    ///   Converted UInt8 value.
    static Uint8 StringToUInt8(const string& str, int base = 10);

    /// Convert string to pointer.
    ///
    /// @param str
    ///   String to be converted.
    /// @return
    ///   Pointer value corresponding to its string representation.
    static const void* StringToPtr(const string& str);

    /// Convert Int to String.
    ///
    /// @param value
    ///   Integer value (long) to be converted.
    /// @param sign
    ///   Whether converted value should be preceded by the sign (+-) character.  
    /// @return
    ///   Converted string value.
    static string IntToString(long value, bool sign = false);

    /// Convert Int to String.
    ///
    /// @param out_str
    ///   Output string variable
    /// @param value
    ///   Integer value (long) to be converted.
    /// @param sign
    ///   Whether converted value should be preceded by the sign (+-) character.  
    static void IntToString(string& out_str, long value, bool sign = false);


    /// Convert UInt to string.
    ///
    /// @param value
    ///   Integer value (unsigned long) to be converted.
    /// @return
    ///   Converted string value.
    static string UIntToString(unsigned long value);

    /// Convert UInt to string.
    ///
    /// @param out_str
    ///   Output string variable
    /// @param value
    ///   Integer value (unsigned long) to be converted.
    static void UIntToString(string& out_str, unsigned long value);

    /// Convert Int8 to string.
    ///
    /// @param value
    ///   Integer value (Int8) to be converted.
    /// @param sign
    ///   Whether converted value should be preceded by the sign (+-) character.  
    /// @return
    ///   Converted string value.
    static string Int8ToString(Int8 value, bool sign = false);


    /// Convert Int8 to string.
    ///
    /// @param out_str
    ///   Output string variable
    /// @param value
    ///   Integer value (Int8) to be converted.
    /// @param sign
    ///   Whether converted value should be preceded by the sign (+-) character.  
    static void Int8ToString(string& out_str, Int8 value, bool sign = false);

    /// Convert UInt8 to string.
    ///
    /// @param value
    ///   Integer value (UInt8) to be converted.
    /// @return
    ///   Converted string value.
    static string UInt8ToString(Uint8 value);

    /// Convert UInt8 to string.
    ///
    /// @param out_str
    ///   Output string variable
    /// @param value
    ///   Integer value (UInt8) to be converted.
    static void UInt8ToString(string& out_str, Uint8 value);

    /// Convert double to string.
    ///
    /// @param value
    ///   Double value to be converted.
    /// @return
    ///   Converted string value.
    static string DoubleToString(double value);

    /// Convert double to string.
    ///
    /// @param out_str
    ///   Output string variable
    /// @param value
    ///   Double value to be converted.
    static void DoubleToString(string& out_str, double value);


    /// Convert double to string with specified precision.
    ///
    /// @param value
    ///   Double value to be converted.
    /// @param precision
    ///   Precision value for conversion. If precision is more that maximum
    ///   for current platform, then it will be truncated to this maximum.
    /// @return
    ///   Converted string value.
    static string DoubleToString(double value, unsigned int precision);

    /// Convert double to string with specified precision and place the result
    /// in the specified buffer.
    ///
    /// @param value
    ///   Double value to be converted.
    /// @param precision
    ///   Precision value for conversion. If precision is more that maximum
    ///   for current platform, then it will be truncated to this maximum.
    /// @param buf
    ///   Put result of the conversion into this buffer.
    /// @param buf_size
    ///   Size of buffer, "buf".
    /// @return
    ///   The number of bytes stored in "buf", not counting the
    ///   terminating '\0'.
    static SIZE_TYPE DoubleToString(double value, unsigned int precision,
                                    char* buf, SIZE_TYPE buf_size);

    /// Convert pointer to string.
    ///
    /// @param out_str
    ///   Output string variable
    /// @param str
    ///   Pointer to be converted.
    static void PtrToString(string& out_str, const void* ptr);