doxygen
Classes | Functions
util.h File Reference

A bunch of utility functions. More...

#include <memory>
#include <unordered_map>
#include <algorithm>
#include <functional>
#include <fstream>
#include <ctype.h>
#include "types.h"
#include "docparser.h"
#include "containers.h"
#include "outputgen.h"
#include "regex.h"
#include "conceptdef.h"
Include dependency graph for util.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

class  TextGeneratorIntf
 Abstract interface for a hyperlinked text fragment. More...
 
class  TextGeneratorOLImpl
 Implements TextGeneratorIntf for an OutputDocInterface stream. More...
 
struct  ColoredImgDataItem
 Data associated with a HSV colored image. More...
 

Functions

QCString langToString (SrcLangExt lang)
 Returns a string representation of lang. More...
 
QCString getLanguageSpecificSeparator (SrcLangExt lang, bool classScope=FALSE)
 Returns the scope separator to use given the programming language lang.
 
void linkifyText (const TextGeneratorIntf &ol, const Definition *scope, const FileDef *fileScope, const Definition *self, const QCString &text, bool autoBreak=FALSE, bool external=TRUE, bool keepSpaces=FALSE, int indentLevel=0)
 
QCString fileToString (const QCString &name, bool filter=FALSE, bool isSourceCode=FALSE)
 
QCString dateToString (bool)
 
bool getDefs (const QCString &scopeName, const QCString &memberName, const QCString &args, const MemberDef *&md, const ClassDef *&cd, const FileDef *&fd, const NamespaceDef *&nd, const GroupDef *&gd, bool forceEmptyScope=FALSE, const FileDef *currentFile=0, bool checkCV=FALSE)
 
QCString getFileFilter (const QCString &name, bool isSourceCode)
 
bool resolveRef (const QCString &scName, const QCString &name, bool inSeeBlock, const Definition **resContext, const MemberDef **resMember, bool lookForSpecializations=TRUE, const FileDef *currentFile=0, bool checkScope=FALSE)
 
bool resolveLink (const QCString &scName, const QCString &lr, bool inSeeBlock, const Definition **resContext, QCString &resAnchor)
 
bool generateLink (OutputDocInterface &od, const QCString &, const QCString &, bool inSeeBlock, const QCString &)
 
void generateFileRef (OutputDocInterface &od, const QCString &, const QCString &linkTxt=QCString())
 
void writePageRef (OutputDocInterface &od, const QCString &cn, const QCString &mn)
 
QCString getCanonicalTemplateSpec (const Definition *d, const FileDef *fs, const QCString &spec)
 
bool matchArguments2 (const Definition *srcScope, const FileDef *srcFileScope, const ArgumentList *srcAl, const Definition *dstScope, const FileDef *dstFileScope, const ArgumentList *dstAl, bool checkCV)
 
void mergeArguments (ArgumentList &, ArgumentList &, bool forceNameOverwrite=FALSE)
 
QCString substituteClassNames (const QCString &s)
 
QCString clearBlock (const char *s, const char *begin, const char *end)
 
QCString selectBlock (const QCString &s, const QCString &name, bool enable, OutputGenerator::OutputType o)
 
QCString removeEmptyLines (const QCString &s)
 
FileDeffindFileDef (const FileNameLinkedMap *fnMap, const QCString &n, bool &ambig)
 
QCString showFileDefMatches (const FileNameLinkedMap *fnMap, const QCString &n)
 
int guessSection (const QCString &name)
 
bool isId (int c)
 
bool isIdJS (int c)
 
QCString removeRedundantWhiteSpace (const QCString &s)
 
QCString argListToString (const ArgumentList &al, bool useCanonicalType=FALSE, bool showDefVals=TRUE)
 
QCString tempArgListToString (const ArgumentList &al, SrcLangExt lang, bool includeDefaults=true)
 
QCString generateMarker (int id)
 
void writeExamples (OutputList &ol, const ExampleList &el)
 
QCString stripAnonymousNamespaceScope (const QCString &s)
 
QCString stripFromPath (const QCString &path)
 
QCString stripFromIncludePath (const QCString &path)
 
bool rightScopeMatch (const QCString &scope, const QCString &name)
 
bool leftScopeMatch (const QCString &scope, const QCString &name)
 
QCString substituteKeywords (const QCString &s, const QCString &title, const QCString &projName, const QCString &projNum, const QCString &projBrief)
 
int getPrefixIndex (const QCString &name)
 
QCString removeAnonymousScopes (const QCString &s)
 
QCString replaceAnonymousScopes (const QCString &s, const QCString &replacement=QCString())
 
QCString convertNameToFile (const QCString &name, bool allowDots=FALSE, bool allowUnderscore=FALSE)
 
void extractNamespaceName (const QCString &scopeName, QCString &className, QCString &namespaceName, bool allowEmptyClass=FALSE)
 
QCString insertTemplateSpecifierInScope (const QCString &scope, const QCString &templ)
 
QCString stripScope (const QCString &name)
 
QCString convertToId (const QCString &s)
 
QCString correctId (const QCString &s)
 
QCString convertToHtml (const QCString &s, bool keepEntities=TRUE)
 
QCString convertToLaTeX (const QCString &s, bool insideTabbing=FALSE, bool keepSpaces=FALSE)
 
QCString convertToXML (const QCString &s, bool keepEntities=FALSE)
 
QCString convertToDocBook (const QCString &s)
 
QCString convertToJSString (const QCString &s)
 
QCString convertToPSString (const QCString &s)
 
QCString getOverloadDocs ()
 
void addMembersToMemberGroup (MemberList *ml, MemberGroupList *pMemberGroups, const Definition *context)
 
int extractClassNameFromType (const QCString &type, int &pos, QCString &name, QCString &templSpec, SrcLangExt=SrcLangExt_Unknown)
 
QCString normalizeNonTemplateArgumentsInString (const QCString &name, const Definition *context, const ArgumentList &formalArgs)
 
QCString substituteTemplateArgumentsInString (const QCString &name, const ArgumentList &formalArgs, const std::unique_ptr< ArgumentList > &actualArgs)
 
QCString stripTemplateSpecifiersFromScope (const QCString &fullName, bool parentOnly=TRUE, QCString *lastScopeStripped=0)
 
QCString resolveTypeDef (const Definition *d, const QCString &name, const Definition **typedefContext=0)
 
QCString mergeScopes (const QCString &leftScope, const QCString &rightScope)
 
int getScopeFragment (const QCString &s, int p, int *l)
 
void addRefItem (const RefItemVector &sli, const QCString &key, const QCString &prefix, const QCString &name, const QCString &title, const QCString &args, const Definition *scope)
 
PageDefaddRelatedPage (const QCString &name, const QCString &ptitle, const QCString &doc, const QCString &fileName, int docLine, int startLine, const RefItemVector &sli=RefItemVector(), GroupDef *gd=0, const TagInfo *tagInfo=0, bool xref=FALSE, SrcLangExt lang=SrcLangExt_Unknown)
 
QCString escapeCharsInString (const QCString &name, bool allowDots, bool allowUnderscore=FALSE)
 
QCString unescapeCharsInString (const QCString &s)
 
void addGroupListToTitle (OutputList &ol, const Definition *d)
 
void filterLatexString (TextStream &t, const QCString &str, bool insideTabbing, bool insidePre, bool insideItem, bool insideTable, bool keepSpaces)
 
QCString latexEscapeLabelName (const QCString &s)
 
QCString latexEscapeIndexChars (const QCString &s)
 
QCString latexEscapePDFString (const QCString &s)
 
QCString latexFilterURL (const QCString &s)
 
QCString rtfFormatBmkStr (const QCString &name)
 
QCString linkToText (SrcLangExt lang, const QCString &link, bool isFileName)
 
bool checkExtension (const QCString &fName, const QCString &ext)
 
QCString addHtmlExtensionIfMissing (const QCString &fName)
 
QCString stripExtensionGeneral (const QCString &fName, const QCString &ext)
 
QCString stripExtension (const QCString &fName)
 
void replaceNamespaceAliases (QCString &scope, int i)
 
int computeQualifiedIndex (const QCString &name)
 
void addDirPrefix (QCString &fileName)
 
QCString relativePathToRoot (const QCString &name)
 
void createSubDirs (const Dir &d)
 
void clearSubDirs (const Dir &d)
 
QCString stripPath (const QCString &s)
 
bool containsWord (const QCString &s, const char *word)
 returns TRUE iff string s contains word w
 
bool findAndRemoveWord (QCString &s, const char *word)
 removes occurrences of whole word from sentence, while keeps internal spaces and reducing multiple sequences of spaces. More...
 
QCString stripLeadingAndTrailingEmptyLines (const QCString &s, int &docLine)
 Special version of QCString::stripWhiteSpace() that only strips completely blank lines. More...
 
bool updateLanguageMapping (const QCString &extension, const QCString &parser)
 
SrcLangExt getLanguageFromFileName (const QCString &fileName, SrcLangExt defLang=SrcLangExt_Cpp)
 
SrcLangExt getLanguageFromCodeLang (QCString &fileName)
 Routine to handle the language attribute of the `. More...
 
QCString getFileNameExtension (const QCString &fn)
 
void initDefaultExtensionMapping ()
 
void addCodeOnlyMappings ()
 
bool checkIfTypedef (const Definition *scope, const FileDef *fileScope, const QCString &n)
 
QCString parseCommentAsText (const Definition *scope, const MemberDef *member, const QCString &doc, const QCString &fileName, int lineNr)
 
QCString transcodeCharacterStringToUTF8 (const QCString &input)
 
QCString recodeString (const QCString &str, const char *fromEncoding, const char *toEncoding)
 
QCString extractAliasArgs (const QCString &args, size_t pos)
 
int countAliasArguments (const QCString &argList)
 
QCString resolveAliasCmd (const QCString &aliasCmd)
 
std::string expandAlias (const std::string &aliasName, const std::string &aliasValue)
 
void writeTypeConstraints (OutputList &ol, const Definition *d, const ArgumentList &al)
 
QCString convertCharEntitiesToUTF8 (const QCString &s)
 
void stackTrace ()
 
bool readInputFile (const QCString &fileName, BufStr &inBuf, bool filter=TRUE, bool isSourceCode=FALSE)
 read a file name fileName and optionally filter and transcode it
 
QCString filterTitle (const QCString &title)
 
bool patternMatch (const FileInfo &fi, const StringVector &patList)
 
QCString externalLinkTarget (const bool parent=false)
 
QCString externalRef (const QCString &relPath, const QCString &ref, bool href)
 
int nextUtf8CharPosition (const QCString &utf8Str, uint len, uint startPos)
 
void writeMarkerList (OutputList &ol, const std::string &markerText, size_t numMarkers, std::function< void(size_t)> replaceFunc)
 
void writeColoredImgData (const QCString &dir, ColoredImgDataItem data[])
 Writes the intensity only bitmap represented by data as an image to directory dir using the colors defined by HTML_COLORSTYLE_*.
 
QCString replaceColorMarkers (const QCString &str)
 Replaces any markers of the form ##AA in input string str by new markers of the form #AABBCC, where #AABBCC represents a valid color, based on the intensity represented by hex number AA and the current HTML_COLORSTYLE_* settings.
 
bool copyFile (const QCString &src, const QCString &dest)
 Copies the contents of file with name src to the newly created file with name dest. More...
 
QCString extractBlock (const QCString &text, const QCString &marker)
 Returns the section of text, in between a pair of markers. More...
 
int lineBlock (const QCString &text, const QCString &marker)
 Returns the line number of the line following the line with the marker. More...
 
bool isURL (const QCString &url)
 Checks whether the given url starts with a supported protocol.
 
QCString correctURL (const QCString &url, const QCString &relPath)
 Corrects URL url according to the relative path relPath. More...
 
QCString processMarkup (const QCString &s)
 
bool protectionLevelVisible (Protection prot)
 
QCString stripIndentation (const QCString &s)
 
void stripIndentation (QCString &doc, const int indentationLevel)
 
QCString getDotImageExtension ()
 
bool fileVisibleInIndex (const FileDef *fd, bool &genSourceFile)
 
QCString extractDirection (QCString &docs)
 Strip the direction part from docs and return it as a string in canonical form The input docs string can start with e.g. More...
 
void convertProtectionLevel (MemberListType inListType, Protection inProt, int *outListType1, int *outListType2)
 Computes for a given list type inListType, which are the the corresponding list type(s) in the base class that are to be added to this list. More...
 
bool mainPageHasTitle ()
 
bool openOutputFile (const QCString &outFile, std::ofstream &f)
 
void writeExtraLatexPackages (TextStream &t)
 
void writeLatexSpecialFormulaChars (TextStream &t)
 
StringVector split (const std::string &s, const std::string &delimiter)
 split input string s by string delimiter delimiter. returns a vector of non-empty strings that are between the delimiters
 
StringVector split (const std::string &s, const reg::Ex &delimiter)
 split input string s by regular expression delimiter delimiter. returns a vector of non-empty strings that are between the delimiters
 
int findIndex (const StringVector &sv, const std::string &s)
 find the index of a string in a vector of strings, returns -1 if the string could not be found
 
int findIndex (const std::string &s, const reg::Ex &re)
 find the index of the first occurrence of pattern re in a string s returns -1 if the pattern could not be found
 
std::string join (const StringVector &s, const std::string &delimiter)
 create a string where the string in the vector are joined by the given delimiter
 
bool recognizeFixedForm (const QCString &contents, FortranFormat format)
 
FortranFormat convertFileNameFortranParserCode (QCString fn)
 
QCString integerToAlpha (int n, bool upper=true)
 
QCString integerToRoman (int n, bool upper=true)
 

Detailed Description

A bunch of utility functions.

Function Documentation

◆ checkIfTypedef()

bool checkIfTypedef ( const Definition scope,
const FileDef fileScope,
const QCString n 
)

Returns true iff the given name string appears to be a typedef in scope.

◆ convertNameToFile()

QCString convertNameToFile ( const QCString name,
bool  allowDots,
bool  allowUnderscore 
)

This function determines the file name on disk of an item given its name, which could be a class name with template arguments, so special characters need to be escaped.

◆ convertProtectionLevel()

void convertProtectionLevel ( MemberListType  inListType,
Protection  inProt,
int *  outListType1,
int *  outListType2 
)

Computes for a given list type inListType, which are the the corresponding list type(s) in the base class that are to be added to this list.

So for public inheritance, the mapping is 1-1, so outListType1=inListType Private members are to be hidden completely.

For protected inheritance, both protected and public members of the base class should be joined in the protected member section.

For private inheritance, both protected and public members of the base class should be joined in the private member section.

◆ convertToDocBook()

QCString convertToDocBook ( const QCString s)

Converts a string to an DocBook-encoded string

◆ convertToHtml()

QCString convertToHtml ( const QCString s,
bool  keepEntities 
)

Converts a string to a HTML-encoded string

◆ convertToId()

QCString convertToId ( const QCString s)

Converts a string to a HTML id string

◆ convertToXML()

QCString convertToXML ( const QCString s,
bool  keepEntities 
)

Converts a string to an XML-encoded string

◆ copyFile()

bool copyFile ( const QCString src,
const QCString dest 
)

Copies the contents of file with name src to the newly created file with name dest.

Returns TRUE if successful.

◆ correctId()

QCString correctId ( const QCString s)

Some strings have been corrected but the requirement regarding the fact that an id cannot have a digit at the first position. To overcome problems with double labels we always place an "a" in front

◆ correctURL()

QCString correctURL ( const QCString url,
const QCString relPath 
)

Corrects URL url according to the relative path relPath.

Returns the corrected URL. For absolute URLs no correction will be done.

◆ extractBlock()

QCString extractBlock ( const QCString text,
const QCString marker 
)

Returns the section of text, in between a pair of markers.

Full lines are returned, excluding the lines on which the markers appear.

See also
routine lineBlock

◆ extractClassNameFromType()

int extractClassNameFromType ( const QCString type,
int &  pos,
QCString name,
QCString templSpec,
SrcLangExt  lang 
)

Extracts a (sub-)string from type starting at pos that could form a class. The index of the match is returned and the found class name and a template argument list templSpec. If -1 is returned there are no more matches.

◆ extractDirection()

QCString extractDirection ( QCString docs)

Strip the direction part from docs and return it as a string in canonical form The input docs string can start with e.g.

"[in]", "[in, out]", "[inout]", "[out,in]"...

Returns
either "[in,out]", "[in]", or "[out]" or the empty string.

◆ extractNamespaceName()

void extractNamespaceName ( const QCString scopeName,
QCString className,
QCString namespaceName,
bool  allowEmptyClass 
)

Input is a scopeName, output is the scopename split into a namespace part (as large as possible) and a classname part.

◆ fileToString()

QCString fileToString ( const QCString name,
bool  filter,
bool  isSourceCode 
)

reads a file with name name and returns it as a string. If filter is TRUE the file will be filtered by any user specified input filter. If name is "-" the string will be read from standard input.

◆ findAndRemoveWord()

bool findAndRemoveWord ( QCString sentence,
const char *  word 
)

removes occurrences of whole word from sentence, while keeps internal spaces and reducing multiple sequences of spaces.

Example: sentence=cat+ catfish cat cat concat cat, word=cat returns: + catfish concat

◆ generateMarker()

QCString generateMarker ( int  id)

Generate a place holder for a position in a list. Used for translators to be able to specify different elements orders depending on whether text flows from left to right or visa versa.

◆ getDefs()

bool getDefs ( const QCString scName,
const QCString mbName,
const QCString args,
const MemberDef *&  md,
const ClassDef *&  cd,
const FileDef *&  fd,
const NamespaceDef *&  nd,
const GroupDef *&  gd,
bool  forceEmptyScope,
const FileDef currentFile,
bool  checkCV 
)

Searches for a member definition given its name 'memberName' as a string. memberName may also include a (partial) scope to indicate the scope in which the member is located.

The parameter 'scName' is a string representing the name of the scope in which the link was found.

In case of a function args contains a string representation of the argument list. Passing 0 means the member has no arguments. Passing "()" means any argument list will do, but "()" is preferred.

The function returns TRUE if the member is known and documented or FALSE if it is not. If TRUE is returned parameter 'md' contains a pointer to the member definition. Furthermore exactly one of the parameter 'cd', 'nd', or 'fd' will be non-zero:

  • if 'cd' is non zero, the member was found in a class pointed to by cd.
  • if 'nd' is non zero, the member was found in a namespace pointed to by nd.
  • if 'fd' is non zero, the member was found in the global namespace of file fd.

◆ getFileFilter()

QCString getFileFilter ( const QCString name,
bool  isSourceCode 
)

looks for a filter for the file name. Returns the name of the filter if there is a match for the file name, otherwise an empty string. In case inSourceCode is TRUE then first the source filter list is considered.

◆ getLanguageFromCodeLang()

SrcLangExt getLanguageFromCodeLang ( QCString fileName)

Routine to handle the language attribute of the `.

` command

◆ getOverloadDocs()

QCString getOverloadDocs ( )

Returns the standard string that is generated when the \overload command is used.

◆ getPrefixIndex()

int getPrefixIndex ( const QCString name)

Returns the character index within name of the first prefix in Config_getList(IGNORE_PREFIX) that matches name at the left hand side, or zero if no match was found

◆ getScopeFragment()

int getScopeFragment ( const QCString s,
int  p,
int *  l 
)

Returns a fragment from scope s, starting at position p.

Parameters
sthe scope name as a string.
pthe start position (0 is the first).
lthe resulting length of the fragment.
Returns
the location of the fragment, or -1 if non is found.

◆ guessSection()

int guessSection ( const QCString name)

try to determine if name is a source or a header file name by looking at the extension. A number of variations is allowed in both upper and lower case) If anyone knows or uses another extension please let me know :-)

◆ langToString()

QCString langToString ( SrcLangExt  lang)

Returns a string representation of lang.

◆ lineBlock()

int lineBlock ( const QCString text,
const QCString marker 
)

Returns the line number of the line following the line with the marker.

See also
routine extractBlock

◆ mergeScopes()

QCString mergeScopes ( const QCString leftScope,
const QCString rightScope 
)

Merges two scope parts together. The parts may (partially) overlap. Example1: A::B and B::C will result in A::B::C
Example2: A and B will be A::B
Example3: A::B and B will be A::B

Parameters
leftScopethe left hand part of the scope.
rightScopethe right hand part of the scope.
Returns
the merged scope.

◆ removeAnonymousScopes()

QCString removeAnonymousScopes ( const QCString str)

Removes all anonymous scopes from string s Possible examples:

   "bla::@10::blep"      => "bla::blep"
   "bla::@10::@11::blep" => "bla::blep"
   "@10::blep"           => "blep"
   " @10::blep"          => "blep"
   "@9::@10::blep"       => "blep"
   "bla::@1"             => "bla"
   "bla::@1::@2"         => "bla"
   "bla @1"              => "bla"

◆ resolveRef()

bool resolveRef ( const QCString scName,
const QCString name,
bool  inSeeBlock,
const Definition **  resContext,
const MemberDef **  resMember,
bool  lookForSpecialization,
const FileDef currentFile,
bool  checkScope 
)

Returns an object to reference to given its name and context

Postcondition
return value TRUE implies *resContext!=0 or *resMember!=0

◆ stripFromIncludePath()

QCString stripFromIncludePath ( const QCString path)

strip part of path if it matches one of the paths in the Config_getList(INCLUDE_PATH) list

◆ stripFromPath()

QCString stripFromPath ( const QCString path)

strip part of path if it matches one of the paths in the Config_getList(STRIP_FROM_PATH) list

◆ stripLeadingAndTrailingEmptyLines()

QCString stripLeadingAndTrailingEmptyLines ( const QCString s,
int &  docLine 
)

Special version of QCString::stripWhiteSpace() that only strips completely blank lines.

Parameters
sthe string to be stripped
docLinethe line number corresponding to the start of the string. This will be adjusted based on the number of lines stripped from the start.
Returns
The stripped string.

◆ stripScope()

QCString stripScope ( const QCString name)

Strips the scope from a name. Examples: A::B will return A and A<T>::B<N::C<D> > will return A<T>.

◆ stripTemplateSpecifiersFromScope()

QCString stripTemplateSpecifiersFromScope ( const QCString fullName,
bool  parentOnly,
QCString pLastScopeStripped 
)

Strips template specifiers from scope fullName, except those that make up specialized classes. The switch parentOnly determines whether or not a template "at the end" of a scope should be considered, e.g. with parentOnly is TRUE, A<T>::B<S> will try to strip <T> and not <S>, while parentOnly is FALSE will strip both unless A<T> or B<S> are specialized template classes.

◆ substituteTemplateArgumentsInString()

QCString substituteTemplateArgumentsInString ( const QCString nm,
const ArgumentList formalArgs,
const std::unique_ptr< ArgumentList > &  actualArgs 
)

Substitutes any occurrence of a formal argument from argument list formalArgs in name by the corresponding actual argument in argument list actualArgs. The result after substitution is returned as a string. The argument name is used to prevent recursive substitution.