// Copyright (C) 2006 Davis E. King (davisking@users.sourceforge.net) // License: Boost Software License See LICENSE.txt for the full license. #undef DLIB_STRINg_ABSTRACT_ #ifdef DLIB_STRINg_ABSTRACT_ #include <string> #include <iostream> #include "../error.h" namespace dlib { // ---------------------------------------------------------------------------------------- class string_cast_error : public error { public: string_cast_error():error(ECAST_TO_STRING) {} }; template < typename T, typename charT, typename traits, typename alloc > const T string_cast ( const std::basic_string<charT,traits,alloc>& str ); /*! requires - T is not a pointer type ensures - returns str converted to T throws - string_cast_error This exception is thrown if string_cast() is unable to convert str into a T. Also, string_cast_error::info == str !*/ // ---------------------------------------------------------------------------------------- class cast_to_string_error : public error { public: cast_to_string_error():error(ECAST_TO_STRING) {} }; template < typename T > const std::string cast_to_string ( const T& item ); /*! requires - T is not a pointer type ensures - returns item converted to std::string throws - cast_to_string_error This exception is thrown if cast_to_string() is unable to convert item into a std::string. !*/ template < typename T > const std::wstring cast_to_wstring ( const T& item ); /*! requires - T is not a pointer type ensures - returns item converted to std::wstring throws - cast_to_string_error This exception is thrown if cast_to_string() is unable to convert item into a std::string. !*/ // ---------------------------------------------------------------------------------------- template < typename charT, typename traits, typename alloc > const std::string narrow ( const std::basic_string<charT,traits,alloc>& str ); /*! ensures - returns str as a std::string by converting every character in it to a char. Note that any characters that do not have a mapping to type char will be converted to a space. !*/ // ---------------------------------------------------------------------------------------- template < typename charT, typename traits, typename alloc > const std::basic_string<charT,traits,alloc> wrap_string ( const std::basic_string<charT,traits,alloc>& str, const unsigned long first_pad, const unsigned long rest_pad, const unsigned long max_per_line = 79 ); /*! requires - first_pad < max_per_line - rest_pad < max_per_line - rest_pad >= first_pad ensures - returns a copy of str S such that: - S is broken up into lines separated by the \n character. - The first line starts with first_pad space characters. - The second and all subsequent lines start with rest_pad space characters. - The first line is no longer than max_per_line - (rest_pad-first_pad) characters. - The second and all subsequent lines are no longer than max_per_line characters. !*/ // ---------------------------------------------------------------------------------------- template < typename traits typename alloc > const std::basic_string<char,traits,alloc> tolower ( const std::basic_string<char,traits,alloc>& str ); /*! ensures - returns a copy of str S such that: - #S.size() == str.size() - #S[i] == std::tolower(str[i]) !*/ // ---------------------------------------------------------------------------------------- template < typename traits, typename alloc > const std::basic_string<char,traits,alloc> toupper ( const std::basic_string<char,traits,alloc>& str ); /*! ensures - returns a copy of str S such that: - #S.size() == str.size() - #S[i] == std::toupper(str[i]) !*/ // ---------------------------------------------------------------------------------------- template < typename charT, typename traits, typename alloc > const std::basic_string<charT,traits,alloc> ltrim ( const std::basic_string<charT,traits,alloc>& str, const std::basic_string<charT,traits,alloc>& trim_chars ); /*! ensures - returns a copy of str with any leading trim_chars from the left side of the string removed. !*/ template < typename charT, typename traits, typename alloc > const std::basic_string<charT,traits,alloc> ltrim ( const std::basic_string<charT,traits,alloc>& str, const charT* trim_chars = _dT(charT," \t\r\n") ); /*! ensures - returns ltrim(str, std::basic_string<charT,traits,alloc>(trim_chars)) !*/ // ---------------------------------------------------------------------------------------- template < typename charT, typename traits, typename alloc > const std::basic_string<charT,traits,alloc> rtrim ( const std::basic_string<charT,traits,alloc>& str, const std::basic_string<charT,traits,alloc>& trim_chars ); /*! ensures - returns a copy of str with any trailing trim_chars from the right side of the string removed. !*/ template < typename charT, typename traits, typename alloc > const std::basic_string<charT,traits,alloc> rtrim ( const std::basic_string<charT,traits,alloc>& str, const charT* trim_chars = _dT(charT," \t\r\n") ); /*! ensures - returns rtrim(str, std::basic_string<charT,traits,alloc>(trim_chars)) !*/ // ---------------------------------------------------------------------------------------- template < typename charT, typename traits, typename alloc > const std::basic_string<charT,traits,alloc> trim ( const std::basic_string<charT,traits,alloc>& str, const std::basic_string<charT,traits,alloc>& trim_chars ); /*! ensures - returns a copy of str with any leading or trailing trim_chars from the ends of the string removed. !*/ template < typename charT, typename traits, typename alloc > const std::basic_string<charT,traits,alloc> trim ( const std::basic_string<charT,traits,alloc>& str, const charT* trim_chars = _dT(charT," \t\r\n") ); /*! ensures - returns trim(str, std::basic_string<charT,traits,alloc>(trim_chars)) !*/ // ---------------------------------------------------------------------------------------- template < typename charT, typename traits, typename alloc > const std::basic_string<charT,traits,alloc> rpad ( const std::basic_string<charT,traits,alloc>& str, long pad_length, const std::basic_string<charT,traits,alloc>& pad_string ); /*! ensures - if (pad_length <= str.size()) then - returns str - else - let P be a string defined as follows: - P.size() == pad_length - str.size() - P == (pad_string + pad_string + ... + pad_string).substr(0,pad_length - str.size()) (i.e. P == a string with the above specified size that contains just repitions of the pad_string) - returns the string str + P !*/ template < typename charT, typename traits, typename alloc > const std::basic_string<charT,traits,alloc> rpad ( const std::basic_string<charT,traits,alloc>& str, long pad_length, const charT* pad_string = _dT(charT," ") ); /*! ensures - returns rpad(str, pad_length, std::basic_string<charT,traits,alloc>(pad_string)) !*/ // ---------------------------------------------------------------------------------------- template < typename charT, typename traits, typename alloc > const std::basic_string<charT,traits,alloc> lpad ( const std::basic_string<charT,traits,alloc>& str, long pad_length, const std::basic_string<charT,traits,alloc>& pad_string ); /*! ensures - if (pad_length <= str.size()) then - returns str - else - let P be a string defined as follows: - P.size() == pad_length - str.size() - P == (pad_string + pad_string + ... + pad_string).substr(0,pad_length - str.size()) (i.e. P == a string with the above specified size that contains just repitions of the pad_string) - returns the string P + str !*/ template < typename charT, typename traits, typename alloc > const std::basic_string<charT,traits,alloc> lpad ( const std::basic_string<charT,traits,alloc>& str, long pad_length, const charT* pad_string = _dT(charT," ") ); /*! ensures - returns lpad(str, pad_length, std::basic_string<charT,traits,alloc>(pad_string)) !*/ // ---------------------------------------------------------------------------------------- template < typename charT, typename traits, typename alloc > const std::basic_string<charT,traits,alloc> pad ( const std::basic_string<charT,traits,alloc>& str, long pad_length, const std::basic_string<charT,traits,alloc>& pad_string ); /*! ensures - let str_size == static_cast<long>(str.size()) - returns rpad( lpad(str, (pad_length-str_size)/2 + str_size, pad_string), pad_length, pad_string); !*/ template < typename charT, typename traits, typename alloc > const std::basic_string<charT,traits,alloc> pad ( const std::basic_string<charT,traits,alloc>& str, long pad_length, const charT* pad_string = _dT(charT," ") ); /*! ensures - returns pad(str, pad_length, std::basic_string<charT,traits,alloc>(pad_string)) !*/ // ---------------------------------------------------------------------------------------- template < typename charT, typename traits, typename alloc > const std::basic_string<charT,traits,alloc> left_substr ( const std::basic_string<charT,traits,alloc>& str, const std::basic_string<charT,traits,alloc>& delim ); /*! ensures - let delim_pos = str.find_first_of(delim) - returns str.substr(0,delim_pos) !*/ template < typename charT, typename traits, typename alloc > const std::basic_string<charT,traits,alloc> left_substr ( const std::basic_string<charT,traits,alloc>& str, const charT* delim = _dT(charT," \n\r\t") ); /*! ensures - returns left_substr(str, std::basic_string<charT,traits,alloc>(delim)) !*/ // ---------------------------------------------------------------------------------------- template < typename charT, typename traits, typename alloc > const std::basic_string<charT,traits,alloc> right_substr ( const std::basic_string<charT,traits,alloc>& str, const std::basic_string<charT,traits,alloc>& delim ); /*! ensures - let delim_pos = str.find_last_of(delim) - if (delim_pos == std::string::npos) then - returns "" - else - returns str.substr(delim_pos+1) !*/ template < typename charT, typename traits typename alloc > const std::basic_string<charT,traits,alloc> right_substr ( const std::basic_string<charT,traits,alloc>& str, const charT* delim = _dT(charT," \n\r\t") ); /*! ensures - returns right_substr(str, std::basic_string<charT,traits,alloc>(delim)) !*/ // ---------------------------------------------------------------------------------------- } #endif // DLIB_STRINg_ABSTRACT_