StringUtils.h

//========================================================================================
// 
// $File$
// 
// Owner: Paul Sorrick
// 
// $Author$
// 
// $DateTime$
// 
// $Revision$
// 
// $Change$
// 
// Copyright 1997-2010 Adobe Systems Incorporated. All rights reserved.
// 
// NOTICE: Adobe permits you to use, modify, and distribute this file in accordance 
// with the terms of the Adobe license agreement accompanying it. If you have received
// this file from a source other than Adobe, then your use, modification, or 
// distribution of it requires the prior written permission of Adobe.
// 
//========================================================================================
#ifndef __STRINGUTILS__
#define __STRINGUTILS__

#include "IPMUnknown.h"
#include "PMString.h"
#include "WideString.h"
#include "EscapeTable.h"
#include <algorithm>
#include <utility>
#include "K2Pair.h"
#include <boost/range/iterator_range.hpp>

// Forward declarations
class TextCharFilter;
class IPMStream;


namespace StringUtils
{

 // Array containing the replacement strings.
 typedef K2Vector<WideString> ArgArray;
 
 void FormatPositionalArgs(WideString& formatString, ArgArray const& args);


 // String parameter replacement - NOTE: you should have translated aString before passing it
 // to this routine. It will be marked as non-translating by this routine.
 // Note that more than one occurrence of a placeholder (^1, ^2, ^3, ^4, ^5, ^6, ^7) can occur and
 // all will be replaced with the provided string.
 void ReplaceStringParameters(
 PMString *aString, // Input and output string that contains up to four different placeholders
 const PMString& parm1, // String to replace ^1 with, may be empty
 const PMString& parm2 = kNullString, // String to replace ^2 with, may be empty
 const PMString& parm3 = kNullString, // String to replace ^3 with, may be empty
 const PMString& parm4 = kNullString, // String to replace ^4 with, may be empty
 const PMString& parm5 = kNullString, // String to replace ^5 with, may be empty
 const PMString& parm6 = kNullString, // String to replace ^6 with, may be empty
 const PMString& parm7 = kNullString // String to replace ^7 with, may be empty
 );

 // Input UTF16 String, Returns a PMString Translated to a UTF8 String
 void ConvertWideStringToUTF8 (const WideString & str, std::string & returnval );

 // An iterator range specifies a sequence of characters
 typedef boost::iterator_range<const unsigned char*> UTF8CharRange;
 
 // Helper function - constructs an UTF8CharRange from a std::string
 // This will be removed when ConvertUTF8ToWideString will be a template and it will work with any type of iterators (not only pointers)
 inline UTF8CharRange MakeUTF8CharRange(const std::string& str)
 {
 const unsigned char* b((const unsigned char*)(str.c_str()));
 const unsigned char* e(b + str.size());
 return UTF8CharRange(b, e);
 }
 
 inline UTF8CharRange MakeUTF8CharRange(const char* utf8Buffer, size_t length)
 {
 const unsigned char* b((const unsigned char*)utf8Buffer);
 const unsigned char* e(b + length);
 return UTF8CharRange(b, e);
 }


 UTF8CharRange ConvertUTF8RangeToWideString (const UTF8CharRange& utf8Range, WideString & returnval) ;
 
 // Overload for convenience when you already have a std::string
 // If you have raw pointers use the UTF8CharRange version (faster - avoids std::string construction)
 inline UTF8CharRange ConvertUTF8ToWideString (const std::string& str, WideString & returnval)
 {
 return ConvertUTF8RangeToWideString(::StringUtils::MakeUTF8CharRange(str), returnval);
 }
 
 // Functor that checks if the specified character is in the range [0x20, 0x7E]
 // This range does not include the control characters (like '\t' or 'n') which are below 0x20.
 struct IsPrintableASCII : public std::function<bool (char) >
 {
 inline bool operator()(char c) const
 {
 // Check if c is within the range [0x20-0x7E]
 return (c > 0x1F && c < 0x7F);
 }
 };
 
 void Reverse(WideString& w);

 // std::back_insert_iterator doesn't work with our non-standard containers
 // Optimized insert iterator that saves on re-allocations
 template<class Container>
 class back_insert_iterator
 : public std::iterator<std::output_iterator_tag, void, void, void, void>
 {
 public:
 explicit back_insert_iterator(Container& cont)
 : fContainer(cont)
 {
 }

 back_insert_iterator<Container>& operator=(UTF32TextChar val)
 {
 if ((fContainer.capacity() - fContainer.size()) < 2)
 {
 grow_capacity();
 }

 // push value into container
 fContainer.push_back(val);
 return (*this);
 }

 back_insert_iterator<Container>& operator*()
 {
 return (*this);
 }

 back_insert_iterator<Container>& operator++()
 {
 return (*this);
 }

 back_insert_iterator<Container> operator++(int)
 {
 return (*this);
 }

 back_insert_iterator<Container>& operator=(back_insert_iterator<Container> const&)
 {
 return (*this);
 }

 protected:

 // Grows the capacity of the container by a factor of 1.5
 // We want to have at least two empty slots available at the end.
 void grow_capacity(void)
 {
 size_t newSize(1);
 if (fContainer.capacity())
 {
 // Multiply by 1.5
 newSize = fContainer.capacity() + (fContainer.capacity() >> 1);
 }
 fContainer.reserve(++newSize);
 }

 Container& fContainer;
 };

 template<> back_insert_iterator<PMString>& back_insert_iterator<PMString>::operator=(UTF32TextChar val);
 template<> back_insert_iterator<WideString>& back_insert_iterator<WideString>::operator=(UTF32TextChar val);

 // Generic back_inserter

 template<class Container>
 inline back_insert_iterator<Container> back_inserter(Container& cont)
 {
 return (::StringUtils::back_insert_iterator<Container>(cont));
 }

 template <typename InputIt, typename OutputIt, typename CharType, typename EscapeType>
 OutputIt Escape( InputIt srcBeg, InputIt srcEnd, OutputIt destBeg,
 EscapeTable<CharType, EscapeType> const& mappingTable )
 {
 typedef typename EscapeTable<CharType, EscapeType>::EscapeMap MapType;
 typedef typename EscapeTable<CharType, EscapeType>::EscapeMapKey MapKeyType;
 typedef typename EscapeTable<CharType, EscapeType>::EscapeMapValue MapValueType;

 MapType const& searchMap = mappingTable.GetEscapeMap();
 ASSERT( !searchMap.empty() );

 for ( ; srcBeg != srcEnd; ++srcBeg )
 {
 MapKeyType key(*srcBeg);
 typename MapType::const_iterator i = searchMap.find( key );
 if ( i != searchMap.end() )
 {
 destBeg = std::copy( i->second.begin(), i->second.end(), destBeg );
 }
 else
 {
 *destBeg++ = *srcBeg;
 }
 }
 return destBeg;
 }


 template <typename InputIt, typename OutputIt, typename CharType, typename EscapeType>
 OutputIt Unescape( InputIt srcBeg, InputIt srcEnd, OutputIt destBeg,
 EscapeTable<CharType, EscapeType> const& mappingTable, bool16* pFoundInvalidEscape = nil )
 {
 typedef typename EscapeTable<CharType, EscapeType>::UnescapeMap MapType;
 typedef typename EscapeTable<CharType, EscapeType>::UnescapeMapKey MapKeyType;
 typedef typename EscapeTable<CharType, EscapeType>::UnescapeMapValue MapValueType;

 if ( pFoundInvalidEscape )
 {
 *pFoundInvalidEscape = kFalse;
 }

 MapType const& searchMap = mappingTable.GetUnescapeMap();
 ASSERT( !searchMap.empty() );

 MapKeyType const& escapeString = searchMap.begin()->first;

 typename MapKeyType::value_type escapeChar = escapeString[0];
 size_t escapeLen = escapeString.size();

 while ( srcBeg != srcEnd )
 {
 // Is it an escape char?
 if ( *srcBeg == escapeChar )
 {
 // Do we have enough chars left to be considered an escape sequence?
 if ( escapeLen <= (size_t)std::distance(srcBeg, srcEnd) )
 {
 //MapKeyType key(srcBeg, srcBeg + escapeLen);
 MapKeyType key;
 std::copy(srcBeg, srcBeg + (int32)escapeLen, std::back_inserter(key) );
 typename MapType::const_iterator i = searchMap.find( key );
 if ( i != searchMap.end() )
 {
 // Replace with the found character
 *destBeg++ = i->second;
 std::advance(srcBeg, escapeLen);
 // Continue with next char
 continue;
 }
 }

 // We either found an invalid combination or a truncated escape sequence
 // Signal that to the caller if it cares
 if ( pFoundInvalidEscape )
 {
 *pFoundInvalidEscape = kTrue;
 }
 }

 // Copy the char to the output unchanged
 *destBeg++ = *srcBeg++;
 }

 return destBeg;
 }

 // Some predefined tables; these are implemented in stringutils.cpp

 // Table for escaping control characters ( '\r', '\n', etc)
 // This table should be used for finding control characters and display them to the UI.
 extern EscapeTable<uint32, char> const kSearchableCtrlCharsTable;

 // This table should be used for replacing control characters.
 // It contains only control chars that are safe to replace in the actual document.
 extern EscapeTable<uint32, char> const kReplaceableCtrlCharsTable;

 // This table should be used for replacing control characters that do not include meta meaning.
 // It contains only control chars that are safe to replace in the actual document and excludes
 // characters such as page number.
 extern EscapeTable<uint32, char> const kReplaceableNoMetaCtrlCharsTable;

 extern EscapeTable<uint32, char> const kSearchableGrepCtrlCharsTable;
 extern EscapeTable<uint32, char> const kReplaceableGrepCtrlCharsTable;

 extern EscapeTable<uint32, char> const kReplaceableXRefFormatCtrlCharsTable;
 
 // This table is used for replacing those special chars to HTML version.
 // extern EscapeTable<uint32, char> const kReplaceableHTMLCharsTable;

 // Predefined XML entities that should be recognized by any XML parser
 extern EscapeTable<uint32, char> const kXMLPredefinedEntitiesCharsTable;

 // Wraps together the C-array and it's size
 typedef K2Pair<textchar const*, size_t> CharArray;

 // Filter for commonly ignored chars.
 extern CharArray const kIgnoredCharsFilterArray;

 // Filter for special control chars
 extern CharArray const kSpecialControlCharsFilterArray;

 // Filter for whitespace (and similar) chars.
 extern CharArray const kWhitespaceCharsFilterArray;

 // Filter for special/variable width whitespace (e.g. CR/LF, tabs, indent to here, etc) chars.
 extern CharArray const kSpecialWhitespaceCharsFilterArray;

 // Filter for proxy chars (e.g. page numbers, footnotes, inlines, etc).
 extern CharArray const kProxyCharsFilterArray;

 // Filter for illegal chars within calculated text (e.g. proxyChars + specialWhitespace + tables-related chars).
 extern CharArray const kCalcTextIllegalCharsFilterArray;

 enum StripType
 {
 kStripLeadingChars = 0,
 kStripTrailingChars,
 kStripLeadingAndTrailingChars,
 }; 

 void StripBeginEndChars( WideString& text, CharArray const& charArray, ::StringUtils::StripType stripType);

 template<class PR> void StripBeginEndChars( WideString& text, PR filter, ::StringUtils::StripType stripType)
 { 
 // remove leading characters
 if (stripType == ::StringUtils::kStripLeadingAndTrailingChars || stripType == ::StringUtils::kStripLeadingChars)
 {
 WideString::const_iterator newBegin = text.begin();
 for (; newBegin != text.end(); ++newBegin)
 {
 if (!filter(*newBegin))
 break;
 }
 text.erase(text.begin(), newBegin);
 }

 // remove trailing characters
 if (stripType == ::StringUtils::kStripLeadingAndTrailingChars || stripType == ::StringUtils::kStripTrailingChars)
 {
 WideString::const_reverse_iterator rNewBegin = text.rbegin();
 for (; rNewBegin != text.rend(); ++rNewBegin)
 {
 const UTF32TextChar c = *rNewBegin;
 if (!filter(c))
 break;
 }
 
 text.erase(rNewBegin.base(), text.end());
 }
 }
 
 void FilterString( WideString& text, CharArray const& charArray);

 template<class PR> void FilterString( WideString& text, PR filter)
 {
 WideString::iterator_raw newEnd = std::remove_if(text.begin_raw(), text.end_raw(), filter);
 if ( newEnd != text.end_raw() )
 {
 // text.erase(newEnd, text.end());
 int32 pos = newEnd - text.begin_raw();
 int32 len = text.end_raw() - newEnd;
 text.remove_raw(pos, len);
 }
 }

 WideString ConvertFromUIString(const PMString& ps, EscapeTable<uint32, char> const *escapeTable, const CharArray* stripArray);

 PMString ConvertToUIString(const WideString& ws, EscapeTable<uint32, char> const *escapeTable);

 UTF16TextChar* ConvertInt32ToUTF16(int32 i, UTF16TextChar* wBuffBegin, UTF16TextChar* wBuffEnd);

 // used by PMString::AppendNumber and PMString::AsNumber.

 // @param i the number to Convert
 // @param wBuffBegin the start of the output range
 // @param wBuffEnd the end of the output range
 // @return pointer to trailing null UTF16TextChar* or wBuffBegin if (wBuffEnd - wBuffBegin) is too small
 // */
 UTF16TextChar* ConvertInt64ToUTF16(int64 i, UTF16TextChar* wBuffBegin, UTF16TextChar* wBuffEnd);

 UTF16TextChar* ConvertUInt32ToUTF16(uint32 i, UTF16TextChar* wBuffBegin, UTF16TextChar* wBuffEnd);

 UTF16TextChar* ConvertUInt64ToUTF16(uint64 i, UTF16TextChar* wBuffBegin, UTF16TextChar* wBuffEnd);

 std::string ReadStdString(IPMStream *s);

 void WriteStdString(IPMStream *s, std::string writeString);

 void TokenizeByWhitespace(const WideString& ws, std::vector<WideString>& tokens);

 void NormalizeDigits(PMString *stringToNormalize);

 PMString NormalizeUnicodeString(const PMString &instring);

}

 void ReplaceStringParameters(PMString *aString,const PMString& parm1,const PMString& parm2 = kNullString,
 const PMString& parm3 = kNullString,const PMString& parm4 = kNullString,const PMString& parm5 = kNullString,
 const PMString& parm6 = kNullString,const PMString& parm7 = kNullString);




#endif