util.h File Reference

A bunch of utility functions. More...

#include <qlist.h>
#include <ctype.h>
#include "types.h"
#include "sortdict.h"
#include "docparser.h"

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...
class	LetterToIndexMap< T >
	maps a unicode character code to a list of T::ElementType's 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, Definition *scope, FileDef *fileScope, Definition *self, const char *text, bool autoBreak=FALSE, bool external=TRUE, bool keepSpaces=FALSE, int indentLevel=0)
void	setAnchors (MemberList *ml)
QCString	fileToString (const char *name, bool filter=FALSE, bool isSourceCode=FALSE)
QCString	dateToString (bool)
bool	getDefs (const QCString &scopeName, const QCString &memberName, const char *, MemberDef *&md, ClassDef *&cd, FileDef *&fd, NamespaceDef *&nd, GroupDef *&gd, bool forceEmptyScope=FALSE, FileDef *currentFile=0, bool checkCV=FALSE, const char *forceTagFile=0)
QCString	getFileFilter (const char *name, bool isSourceCode)
bool	resolveRef (const char *scName, const char *name, bool inSeeBlock, Definition **resContext, MemberDef **resMember, bool lookForSpecializations=TRUE, FileDef *currentFile=0, bool checkScope=FALSE)
bool	resolveLink (const char *scName, const char *lr, bool inSeeBlock, Definition **resContext, QCString &resAnchor)
bool	generateLink (OutputDocInterface &od, const char *, const char *, bool inSeeBlock, const char *)
void	generateFileRef (OutputDocInterface &od, const char *, const char *linkTxt=0)
void	writePageRef (OutputDocInterface &od, const char *cn, const char *mn)
QCString	getCanonicalTemplateSpec (Definition *d, FileDef *fs, const QCString &spec)
bool	matchArguments2 (Definition *srcScope, FileDef *srcFileScope, ArgumentList *srcAl, Definition *dstScope, FileDef *dstFileScope, ArgumentList *dstAl, bool checkCV)
void	mergeArguments (ArgumentList *, ArgumentList *, bool forceNameOverwrite=FALSE)
QCString	substituteClassNames (const QCString &s)
QCString	substitute (const QCString &s, const QCString &src, const QCString &dst)
	substitute all occurrences of src in s by dst
QCString	clearBlock (const char *s, const char *begin, const char *end)
	Clear a text block s from begin to end markers.
QCString	selectBlock (const QCString &s, const QCString &name, bool which)
QCString	resolveDefines (const char *n)
ClassDef *	getClass (const char *key)
ClassDef *	getResolvedClass (Definition *scope, FileDef *fileScope, const char *key, MemberDef **pTypeDef=0, QCString *pTemplSpec=0, bool mayBeUnlinkable=FALSE, bool mayBeHidden=FALSE, QCString *pResolvedType=0)
NamespaceDef *	getResolvedNamespace (const char *key)
FileDef *	findFileDef (const FileNameDict *fnDict, const char *n, bool &ambig)
QCString	showFileDefMatches (const FileNameDict *fnDict, const char *n)
int	guessSection (const char *name)
bool	isId (int c)
QCString	removeRedundantWhiteSpace (const QCString &s)
QCString	argListToString (ArgumentList *al, bool useCanonicalType=FALSE, bool showDefVals=TRUE)
QCString	tempArgListToString (ArgumentList *al, SrcLangExt lang)
QCString	generateMarker (int id)
void	writeExample (OutputList &ol, ExampleSDict *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 char *title, const char *projName, const char *projNum, const char *projBrief)
int	getPrefixIndex (const QCString &name)
QCString	removeAnonymousScopes (const QCString &s)
QCString	replaceAnonymousScopes (const QCString &s, const char *replacement=0)
void	initClassHierarchy (ClassSDict *cl)
bool	hasVisibleRoot (BaseClassList *bcl)
bool	classHasVisibleChildren (ClassDef *cd)
bool	namespaceHasVisibleChild (NamespaceDef *nd, bool includeClasses)
bool	classVisibleInIndex (ClassDef *cd)
int	minClassDistance (const ClassDef *cd, const ClassDef *bcd, int level=0)
Protection	classInheritedProtectionLevel (ClassDef *cd, ClassDef *bcd, Protection prot=Public, int level=0)
QCString	convertNameToFile (const char *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 char *name)
QCString	convertToId (const char *s)
QCString	convertToHtml (const char *s, bool keepEntities=TRUE)
QCString	convertToLaTeX (const QCString &s, bool insideTabbing=FALSE, bool keepSpaces=FALSE)
QCString	convertToXML (const char *s)
QCString	convertToJSString (const char *s)
QCString	getOverloadDocs ()
void	addMembersToMemberGroup (MemberList *ml, MemberGroupSDict **ppMemberGroupSDict, Definition *context)
int	extractClassNameFromType (const QCString &type, int &pos, QCString &name, QCString &templSpec, SrcLangExt=SrcLangExt_Unknown)
QCString	normalizeNonTemplateArgumentsInString (const QCString &name, Definition *context, const ArgumentList *formalArgs)
QCString	substituteTemplateArgumentsInString (const QCString &name, ArgumentList *formalArgs, ArgumentList *actualArgs)
QList< ArgumentList > *	copyArgumentLists (const QList< ArgumentList > *srcLists)
QCString	stripTemplateSpecifiersFromScope (const QCString &fullName, bool parentOnly=TRUE, QCString *lastScopeStripped=0)
QCString	resolveTypeDef (Definition *d, const QCString &name, Definition **typedefContext=0)
QCString	mergeScopes (const QCString &leftScope, const QCString &rightScope)
int	getScopeFragment (const QCString &s, int p, int *l)
int	filterCRLF (char *buf, int len)
void	addRefItem (const QList< ListItemInfo > *sli, const char *prefix, const char *key, const char *name, const char *title, const char *args, Definition *scope)
PageDef *	addRelatedPage (const char *name, const QCString &ptitle, const QCString &doc, QList< SectionInfo > *anchors, const char *fileName, int startLine, const QList< ListItemInfo > *sli, GroupDef *gd=0, TagInfo *tagInfo=0, SrcLangExt lang=SrcLangExt_Unknown)
QCString	escapeCharsInString (const char *name, bool allowDots, bool allowUnderscore=FALSE)
void	addGroupListToTitle (OutputList &ol, Definition *d)
void	filterLatexString (FTextStream &t, const char *str, bool insideTabbing=FALSE, bool insidePre=FALSE, bool insideItem=FALSE, bool keepSpaces=FALSE)
QCString	latexEscapeLabelName (const char *s, bool insideTabbing)
QCString	latexEscapeIndexChars (const char *s, bool insideTabbing)
QCString	latexEscapePDFString (const char *s)
QCString	rtfFormatBmkStr (const char *name)
QCString	linkToText (SrcLangExt lang, const char *link, bool isFileName)
bool	checkExtension (const char *fName, const char *ext)
QCString	stripExtensionGeneral (const char *fName, const char *ext)
QCString	stripExtension (const char *fName)
void	replaceNamespaceAliases (QCString &scope, int i)
int	isAccessibleFrom (Definition *scope, FileDef *fileScope, Definition *item)
int	isAccessibleFromWithExpScope (Definition *scope, FileDef *fileScope, Definition *item, const QCString &explicitScopePart)
int	computeQualifiedIndex (const QCString &name)
void	addDirPrefix (QCString &fileName)
QCString	relativePathToRoot (const char *name)
void	createSubDirs (QDir &d)
QCString	stripPath (const char *s)
bool	containsWord (const QCString &s, const QCString &word)
	returns TRUE iff string s contains word w
bool	findAndRemoveWord (QCString &s, const QCString &word)
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)
void	initDefaultExtensionMapping ()
void	addCodeOnlyMappings ()
MemberDef *	getMemberFromSymbol (Definition *scope, FileDef *fileScope, const char *n)
bool	checkIfTypedef (Definition *scope, FileDef *fileScope, const char *n)
ClassDef *	newResolveTypedef (FileDef *fileScope, MemberDef *md, MemberDef **pMemType=0, QCString *pTemplSpec=0, QCString *pResolvedType=0, ArgumentList *actTemplParams=0)
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, int pos)
int	countAliasArguments (const QCString argList)
QCString	resolveAliasCmd (const QCString aliasCmd)
QCString	expandAlias (const QCString &aliasName, const QCString &aliasValue)
void	writeTypeConstraints (OutputList &ol, Definition *d, ArgumentList *al)
QCString	convertCharEntitiesToUTF8 (const QCString &s)
void	stackTrace ()
bool	readInputFile (const char *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 QFileInfo &fi, const QStrList *patList)
QCString	externalLinkTarget ()
QCString	externalRef (const QCString &relPath, const QCString &ref, bool href)
int	nextUtf8CharPosition (const QCString &utf8Str, int len, int startPos)
const char *	writeUtf8Char (FTextStream &t, const char *s)
void	writeColoredImgData (const char *dir, ColoredImgDataItem data[])
	Writes the intensity only bitmap representated by data as an image to directory dir using the colors defined by HTML_COLORSTYLE_*.
QCString	replaceColorMarkers (const char *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...
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)
QCString	getDotImageExtension (void)
bool	fileVisibleInIndex (FileDef *fd, bool &genSourceFile)
void	addDocCrossReference (MemberDef *src, MemberDef *dst)
uint	getUtf8Code (const QCString &s, int idx)
	Get one unicode character as an unsigned integer from utf-8 string. More...
uint	getUtf8CodeToLower (const QCString &s, int idx)
	Returns one unicode character as an unsigned integer from utf-8 string, making the character lower case if it was upper case. More...
uint	getUtf8CodeToUpper (const QCString &s, int idx)
	Returns one unicode character as ian unsigned interger from utf-8 string, making the character upper case if it was lower case. More...
QCString	extractDirection (QCString &docs)
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 char *outFile, QFile &f)
void	writeExtraLatexPackages (FTextStream &t)

Detailed Description

A bunch of utility functions.

Function Documentation

checkIfTypedef()

bool checkIfTypedef	(	Definition *	scope,
		FileDef *	fileScope,
		const char *	n
	)

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

convertNameToFile()

QCString convertNameToFile	(	const char *	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.

convertToHtml()

QCString convertToHtml	(	const char *	s,
		bool	keepEntities
	)

Converts a string to a HTML-encoded string

convertToId()

QCString convertToId

(

const char *

s

)

Converts a string to a HTML id string

convertToXML()

QCString convertToXML

(

const char *

s

)

Converts a string to an XML-encoded string

copyArgumentLists()

QList<ArgumentList>* copyArgumentLists

(

const QList< ArgumentList > *

srcLists

)

Makes a deep copy of the list of argument lists srcLists. Will allocate memory, that is owned by the caller.

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.

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.

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 char *	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.

filterCRLF()

int filterCRLF	(	char *	buf,
		int	len
	)

takes the buf of the given length len and converts CR LF (DOS) or CR (MAC) line ending to LF (Unix). Returns the length of the converted content (i.e. the same as len (Unix, MAC) or smaller (DOS).

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.

getClass()

ClassDef* getClass

(

const char *

n

)

Get a class definition given its name. Returns 0 if the class is not found.

getDefs()

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

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 char *	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.

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

s	the scope name as a string.
p	the start position (0 is the first).
l	the resulting length of the fragment.

Returns

the location of the fragment, or -1 if non is found.

getUtf8Code()

uint getUtf8Code	(	const QCString &	s,
		int	idx
	)

Get one unicode character as an unsigned integer from utf-8 string.

Parameters

s	utf-8 encoded string
idx	byte position of given string s.

Returns

the unicode codepoint, 0 - MAX_UNICODE_CODEPOINT

See also

getNextUtf8OrToLower()

getNextUtf8OrToUpper()

getUtf8CodeToLower()

uint getUtf8CodeToLower	(	const QCString &	s,
		int	idx
	)

Returns one unicode character as an unsigned integer from utf-8 string, making the character lower case if it was upper case.

Parameters

s	utf-8 encoded string
idx	byte position of given string s.

Returns

the unicode codepoint, 0 - MAX_UNICODE_CODEPOINT, excludes 'A'-'Z'

See also

getNextUtf8Code()

getUtf8CodeToUpper()

uint getUtf8CodeToUpper	(	const QCString &	s,
		int	idx
	)

Returns one unicode character as ian unsigned interger from utf-8 string, making the character upper case if it was lower case.

Parameters

s	utf-8 encoded string
idx	byte position of given string s.

Returns

the unicode codepoint, 0 - MAX_UNICODE_CODEPOINT, excludes 'A'-'Z'

See also

getNextUtf8Code()

guessSection()

int guessSection

(

const char *

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

leftScope	the left hand part of the scope.
rightScope	the right hand part of the scope.

Returns

the merged scope.

newResolveTypedef()

ClassDef* newResolveTypedef	(	FileDef *	fileScope,
		MemberDef *	md,
		MemberDef **	pMemType,
		QCString *	pTemplSpec,
		QCString *	pResolvedType,
		ArgumentList *	actTemplParams
	)

Returns the class representing the value of the typedef represented by md within file fileScope.

Example: typedef A T; will return the class representing A if it is a class.

Example: typedef int T; will return 0, since "int" is not a class.

removeAnonymousScopes()

QCString removeAnonymousScopes

(

const QCString &

s

)

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 char *	scName,
		const char *	name,
		bool	inSeeBlock,
		Definition **	resContext,
		MemberDef **	resMember,
		bool	lookForSpecialization,
		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

s	the string to be stripped
docLine	the 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.

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 &	name,
		ArgumentList *	formalArgs,
		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.