DCMTK  Version 3.6.7
OFFIS DICOM Toolkit
Classes | Public Types | Static Public Member Functions | List of all members
OFStandard Class Reference

A class for various helper functions. More...

Classes

class  OFGroup
 A non-POD version of "struct group" for thread- and memory-safe data access. More...
 
class  OFPasswd
 A non-POD version of "struct passwd" for thread- and memory-safe data access. More...
 

Public Types

enum  E_MarkupMode { MM_HTML , MM_HTML32 , MM_XHTML , MM_XML }
 Markup language mode. More...
 

Static Public Member Functions

static size_t strlcpy (char *dst, const char *src, size_t siz)
 This function copies up to size - 1 characters from the NUL- terminated string src to dst, NUL-terminating the result. More...
 
static size_t strlcat (char *dst, const char *src, size_t siz)
 This function appends the NUL-terminated string src to the end of dst. More...
 
static int snprintf (char *str, size_t size, const char *format,...)
 Standard C99 formatted string output function. More...
 
static int vsnprintf (char *str, size_t size, const char *format, va_list ap)
 Standard C99 formatted string output function. More...
 
static const char * strerror (const int errnum, char *buf, const size_t buflen)
 convert a given error code to a string. More...
 
static OFStringtoUpper (OFString &result, const OFString &value)
 returns the upper-case version of a given string More...
 
static OFStringtoUpper (OFString &value)
 returns the upper-case version of a given string. More...
 
static OFStringtoLower (OFString &result, const OFString &value)
 returns the lower-case version of a given string More...
 
static OFStringtoLower (OFString &value)
 returns the lower-case version of a given string. More...
 
static OFBool pathExists (const OFFilename &pathName)
 check whether the given path exists. More...
 
static OFBool fileExists (const OFFilename &fileName)
 check whether the given file exists. More...
 
static OFBool dirExists (const OFFilename &dirName)
 check whether the given directory exists. More...
 
static OFBool isReadable (const OFFilename &pathName)
 check whether the given path is readable. More...
 
static OFBool isWriteable (const OFFilename &pathName)
 check whether the given path is writeable. More...
 
static OFStringgetDirNameFromPath (OFString &result, const OFString &pathName, const OFBool assumeDirName=OFTrue)
 get directory name component from given path name. More...
 
static OFFilenamegetDirNameFromPath (OFFilename &result, const OFFilename &pathName, const OFBool assumeDirName=OFTrue)
 get directory name component from given path name. More...
 
static OFStringgetFilenameFromPath (OFString &result, const OFString &pathName, const OFBool assumeFilename=OFTrue)
 get file name component from given path name. More...
 
static OFFilenamegetFilenameFromPath (OFFilename &result, const OFFilename &pathName, const OFBool assumeFilename=OFTrue)
 get file name component from given path name. More...
 
static OFStringnormalizeDirName (OFString &result, const OFString &dirName, const OFBool allowEmptyDirName=OFFalse)
 normalize the given directory name. More...
 
static OFFilenamenormalizeDirName (OFFilename &result, const OFFilename &dirName, const OFBool allowEmptyDirName=OFFalse)
 normalize the given directory name. More...
 
static OFStringcombineDirAndFilename (OFString &result, const OFString &dirName, const OFString &fileName, const OFBool allowEmptyDirName=OFFalse)
 combine the given directory and file name. More...
 
static OFFilenamecombineDirAndFilename (OFFilename &result, const OFFilename &dirName, const OFFilename &fileName, const OFBool allowEmptyDirName=OFFalse)
 combine the given directory and file name. More...
 
static OFCondition removeRootDirFromPathname (OFFilename &result, const OFFilename &rootDir, const OFFilename &pathName, const OFBool allowLeadingPathSeparator=OFTrue)
 remove root directory prefix from given path name. More...
 
static OFFilenameappendFilenameExtension (OFFilename &result, const OFFilename &fileName, const OFFilename &fileExtension)
 append a filename extension to the given filename More...
 
static size_t searchDirectoryRecursively (const OFString &directory, OFList< OFString > &fileList, const OFString &pattern="", const OFString &dirPrefix="", const OFBool recurse=OFTrue)
 scan a given directory (recursively) and add all filenames found to a list More...
 
static size_t searchDirectoryRecursively (const OFFilename &directory, OFList< OFFilename > &fileList, const OFFilename &pattern, const OFFilename &dirPrefix, const OFBool recurse=OFTrue)
 scan a given directory (recursively) and add all filenames found to a list More...
 
static OFCondition createDirectory (const OFFilename &dirName, const OFFilename &rootDir)
 create a directory (including sub-directories) if it does not yet exist. More...
 
static OFBool copyFile (const OFFilename &sourceFilename, const OFFilename &destFilename)
 copy an existing file to a new file More...
 
static OFBool deleteFile (const OFFilename &filename)
 delete given file from filesystem More...
 
static OFBool renameFile (const OFFilename &oldFilename, const OFFilename &newFilename)
 change name of a given file More...
 
static size_t getFileSize (const OFFilename &filename)
 determine size of given file (in bytes) More...
 
static OFBool checkForMarkupConversion (const OFString &sourceString, const OFBool convertNonASCII=OFFalse, const size_t maxLength=0)
 check whether conversion to a HTML/XML mnenonic string is required. More...
 
static OFCondition convertToMarkupStream (STD_NAMESPACE ostream &out, const OFString &sourceString, const OFBool convertNonASCII=OFFalse, const E_MarkupMode markupMode=MM_XML, const OFBool newlineAllowed=OFFalse, const size_t maxLength=0)
 convert character string to a HTML/XHTML/XML mnenonic stream. More...
 
static const OFStringconvertToMarkupString (const OFString &sourceString, OFString &markupString, const OFBool convertNonASCII=OFFalse, const E_MarkupMode markupMode=MM_XML, const OFBool newlineAllowed=OFFalse, const size_t maxLength=0)
 convert character string to a HTML/XHTML/XML mnenonic string. More...
 
static OFBool checkForOctalConversion (const OFString &sourceString, const size_t maxLength=0)
 check whether conversion to an octal format is required. More...
 
static OFCondition convertToOctalStream (STD_NAMESPACE ostream &out, const OFString &sourceString, const size_t maxLength=0)
 convert character string to an octal format stream. More...
 
static const OFStringconvertToOctalString (const OFString &sourceString, OFString &octalString, const size_t maxLength=0)
 convert character string to an octal format string. More...
 
static OFCondition encodeBase64 (STD_NAMESPACE ostream &out, const unsigned char *data, const size_t length, const size_t width=0)
 encode binary data according to "Base64" as described in RFC 2045 (MIME). More...
 
static const OFStringencodeBase64 (const unsigned char *data, const size_t length, OFString &result, const size_t width=0)
 encode binary data according to "Base64" as described in RFC 2045 (MIME). More...
 
static size_t decodeBase64 (const OFString &data, unsigned char *&result)
 decode "Base64" encoded string. More...
 
static double atof (const char *s, OFBool *success=NULL)
 converts a floating-point number from an ASCII decimal representation to internal double-precision format. More...
 
static void ftoa (char *target, size_t targetSize, double value, unsigned int flags=0, int width=0, int precision=-1)
 formats a floating-point number into an ASCII string. More...
 

ftoa() processing flags.

These flags can be combined by bit-wise or.

static const unsigned int ftoa_format_e
 Use e or E conversion format instead of g or G.
 
static const unsigned int ftoa_format_f
 Use f or F conversion format instead of g or G.
 
static const unsigned int ftoa_uppercase
 Use E, F or G conversion format instead of e, f or g.
 
static const unsigned int ftoa_alternate
 convert value to alternate form. More...
 
static const unsigned int ftoa_leftadj
 left-justify number be within the field
 
static const unsigned int ftoa_zeropad
 pad with zeroes instead of blanks
 
static unsigned int sleep (unsigned int seconds)
 makes the current process sleep until seconds seconds have elapsed or a signal arrives which is not ignored More...
 
static void milliSleep (unsigned int millisecs)
 makes the current process sleep until the given number of milliseconds have elapsed or a signal which is not ignored arrives More...
 
static long getProcessID ()
 Determines the identification of the running process. More...
 
static OFBool check32BitAddOverflow (const Uint32 summand1, const Uint32 summand2)
 check whether the addition of two 32-bit integers yields in an overflow More...
 
template<typename T >
static OFBool safeSubtract (T minuend, T subtrahend, T &difference)
 check whether subtraction is safe (i.e. no underflow occurs) and if so, perform it (i.e. compute minuend-subtrahend=difference). More...
 
template<typename T >
static OFBool safeAdd (T a, T b, T &sum)
 check whether addition is safe (i.e. no overflow occurs) and if so, perform it (i.e. compute a+b=sum). More...
 
template<typename T >
static OFBool safeMult (T a, T b, T &product)
 check whether multiplication is safe (i.e. no overflow occurs) and if so, perform it (i.e. compute a*b=product). More...
 
template<size_t Count>
static OFBool checkDigits (const char *string)
 checks if a string only contains valid decimal digits, i.e. 0-9. More...
 
template<typename T , size_t Count>
static T extractDigits (const char *)
 extracts digits from a string and converts them to the given integer number type. More...
 
static void trimString (const char *&pBegin, const char *&pEnd)
 An utility function that finds a substring within a string that does not contain leading and trailing spaces and null bytes, effectively trimming the string without unnecessary copies. More...
 
static void trimString (const char *&str, size_t &size)
 An utility function that finds a substring within a string that does not contain leading and trailing spaces and null bytes, effectively trimming the string without unnecessary copies. More...
 
static OFString getHostnameByAddress (const char *addr, int len, int type)
 This function performs a reverse DNS lookup of a hostname. More...
 
static void getAddressByHostname (const char *name, OFSockAddr &result)
 This function performs a DNS lookup of an IP address based on a hostname. More...
 
static OFGroup getGrNam (const char *name)
 Thread-safe version of getgrnam. More...
 
static OFPasswd getPwNam (const char *name)
 Thread-safe version of getpwnam. More...
 
static OFCondition dropPrivileges ()
 On Posix-like platform, this method executes setuid(getuid()), which causes the application to revert from root privileges to those of the calling user when the program is installed as setuid root. More...
 
static OFString getUserName ()
 Retrieve the name of the user that started the current process. More...
 
static OFString getHostName ()
 Retrieve the local domain name, e. More...
 
static void initializeNetwork ()
 Initialize the network API (if necessary), e.g. Winsock. More...
 
static void shutdownNetwork ()
 Shutdown the network API (if necessary), e.g. Winsock. More...
 
static OFerror_code getLastSystemErrorCode ()
 Retrieve the last operating system error code that was emitted in the calling thread. More...
 
static OFerror_code getLastNetworkErrorCode ()
 Retrieve the last network specific error code that was emitted in the calling thread. More...
 
static void forceSleep (Uint32 seconds)
 Method that ensures that the current thread is actually sleeping for the defined number of seconds (at least). More...
 
static size_t my_strlcpy (char *dst, const char *src, size_t siz)
 private implementation of strlcpy. More...
 
static size_t my_strlcat (char *dst, const char *src, size_t siz)
 private implementation of strlcat. More...
 
static unsigned int my_sleep (unsigned int seconds)
 makes the current process sleep until seconds seconds have elapsed or a signal arrives which is not ignored More...
 

Detailed Description

A class for various helper functions.

This class is used to comprise a number of "global" helper functions.

Member Enumeration Documentation

◆ E_MarkupMode

Markup language mode.

Enumerator
MM_HTML 

HTML (Hyper Text Markup Language)

MM_HTML32 

HTML 3.2 (Hyper Text Markup Language)

MM_XHTML 

XHTML (Extensible Hyper Text Markup Language)

MM_XML 

XML (Extensible Markup Language)

Member Function Documentation

◆ appendFilenameExtension()

static OFFilename& OFStandard::appendFilenameExtension ( OFFilename result,
const OFFilename fileName,
const OFFilename fileExtension 
)
static

append a filename extension to the given filename

Parameters
resultstring variable in which the resulting filename is stored. This name may contain wide characters if support is enabled and 'fileName' contains wide characters. In any case, the resulting string is stored with UTF-8 encoding (8-bit) as an alternative representation.
fileNamefilename to which the extension should be appended. This name may contain wide characters if support is enabled. Since there are various constructors for the OFFilename class, a "char *", "OFString" or "wchar_t *" can also be passed directly to this parameter.
fileExtensionfilename extension to be appended (e.g. ".bak"). It is converted to wide characters if 'fileName' contains wide characters.
Returns
reference to the resulting path name (same as 'result')

◆ atof()

static double OFStandard::atof ( const char *  s,
OFBool *  success = NULL 
)
static

converts a floating-point number from an ASCII decimal representation to internal double-precision format.

Unlike the atof() function defined in Posix, this implementation is not affected by a locale setting, the radix character is always assumed to be '.' This implementation does not set errno if the input cannot be parsed and it does not implement special handling for overflow/underflow. It does handle "NaN" and "Inf" (case insensitive; following characters are ignore). A return code indicates whether or not a successful conversion could be performed. The precision of this implementation is limited to approx. 9 decimal digits.

Note
The use of this implementation can be disabled by defining the macro DISABLE_OFSTD_ATOF at compile time; in this case, the locale dependent Posix implementation of sscanf is used and the application is responsible for making sure that the Posix locale is activated at all times.
Parameters
sA decimal ASCII floating-point number, optionally preceded by white space. Must have form "-I.FE-X", where I is the integer part of the mantissa, F is the fractional part of the mantissa, and X is the exponent. Either of the signs may be "+", "-", or omitted. Either I or F may be omitted, or both. The decimal point isn't necessary unless F is present. The "E" may actually be an "e". E and X may both be omitted (but not just one).
successpointer to return status code, may be NULL. if present, a status code is stored in the variable pointed to by this parameter. The status is OFTrue if a conversion could be performed and OFFalse if the string does not have the expected format.
Returns
floating-point equivalent of string. If a terminating character is found before any floating-point digits, then zero is returned.

◆ check32BitAddOverflow()

static OFBool OFStandard::check32BitAddOverflow ( const Uint32  summand1,
const Uint32  summand2 
)
inlinestatic

check whether the addition of two 32-bit integers yields in an overflow

Parameters
summand1first integer value to be added
summand2second integer value to be added
Returns
OFTrue if an overflow occurred during the addition, OFFalse otherwise

◆ checkDigits()

template<size_t Count>
static OFBool OFStandard::checkDigits ( const char *  string)
static

checks if a string only contains valid decimal digits, i.e. 0-9.

Template Parameters
Countthe number of characters (bytes) to check.
Parameters
stringa pointer to a character array to check.
Returns
OFTrue if all characters are valid decimal digits, OFFalse if at least one non-digit character is encountered.

◆ checkForMarkupConversion()

static OFBool OFStandard::checkForMarkupConversion ( const OFString sourceString,
const OFBool  convertNonASCII = OFFalse,
const size_t  maxLength = 0 
)
static

check whether conversion to a HTML/XML mnenonic string is required.

This check can be performed before convertToMarkupStream() or convertToMarkupString() is called in order to speed up the process in case the conversion is not required.

Parameters
sourceStringsource string to be checked. May contain one or more NULL bytes.
convertNonASCIIconvert non-ASCII characters (< #32 and >= #127) to numeric value (&#nnn;) if OFTrue
maxLengthmaximum number of characters from the source string to be converted. A value of 0 means all characters.
Returns
OFTrue if markup conversion is required, OFFalse otherwise

◆ checkForOctalConversion()

static OFBool OFStandard::checkForOctalConversion ( const OFString sourceString,
const size_t  maxLength = 0 
)
static

check whether conversion to an octal format is required.

This check can be performed before convertToOctalStream() or convertToOctalString() is called in order to speed up the process in case the conversion is not required.

Parameters
sourceStringsource string to be checked. May contain one or more NULL bytes.
maxLengthmaximum number of characters from the source string to be converted. A value of 0 means all characters.
Returns
OFTrue if markup conversion is required, OFFalse otherwise

◆ combineDirAndFilename() [1/2]

static OFFilename& OFStandard::combineDirAndFilename ( OFFilename result,
const OFFilename dirName,
const OFFilename fileName,
const OFBool  allowEmptyDirName = OFFalse 
)
static

combine the given directory and file name.

Normalizes the directory name and appends the file name (with a path separator) if not empty. If both 'dirName' and 'fileName' are empty strings and the flag 'allowEmptyDirName' is OFFalse the resulting path name is set to "." (current directory). If 'dirName' is "." and the flag 'allowEmptyDirName' is OFTrue an empty directory name is used. NB: This function neither checks whether the given 'dirName' exists nor whether the resulting path name points to a valid or existing file name. Furthermore, the value of 'dirName' is ignored if 'fileName' starts with a path separator.

Parameters
resultstring variable in which the resulting path name is stored. This name may contain wide characters if support is enabled and 'dirName' as well as 'fileName' contain wide characters. In any case, the resulting string is stored with UTF-8 encoding (8-bit) as an alternative representation.
dirNamedirectory name to be combined with the file name. This name may contain wide characters if support is enabled. Since there are various constructors for the OFFilename class, a "char *", "OFString" or "wchar_t *" can also be passed directly to this parameter.
fileNamefile name to be combined with the directory name. Should contain wide characters if and only if 'dirName' contains wide characters.
allowEmptyDirNameflag indicating whether an empty directory name is allowed
Returns
reference to the resulting path name (same as 'result')

◆ combineDirAndFilename() [2/2]

static OFString& OFStandard::combineDirAndFilename ( OFString result,
const OFString dirName,
const OFString fileName,
const OFBool  allowEmptyDirName = OFFalse 
)
static

combine the given directory and file name.

Normalizes the directory name and appends the file name (with a path separator) if not empty. If both 'dirName' and 'fileName' are empty strings and the flag 'allowEmptyDirName' is OFFalse the resulting path name is set to "." (current directory). If 'dirName' is "." and the flag 'allowEmptyDirName' is OFTrue an empty directory name is used. NB: This function neither checks whether the given 'dirName' exists nor whether the resulting path name points to a valid or existing file name. Furthermore, the value of 'dirName' is ignored if 'fileName' starts with a path separator.

Note
This method is provided for reasons of backward compatibility. Internally, the following method (OFFilename version) is used.
Parameters
resultstring variable in which the resulting path name is stored
dirNamedirectory name to be combined with the file name
fileNamefile name to be combined with the directory name
allowEmptyDirNameflag indicating whether an empty directory name is allowed
Returns
reference to the resulting path name (same as 'result')

◆ convertToMarkupStream()

static OFCondition OFStandard::convertToMarkupStream ( STD_NAMESPACE ostream &  out,
const OFString sourceString,
const OFBool  convertNonASCII = OFFalse,
const E_MarkupMode  markupMode = MM_XML,
const OFBool  newlineAllowed = OFFalse,
const size_t  maxLength = 0 
)
static

convert character string to a HTML/XHTML/XML mnenonic stream.

Characters with special meaning for HTML/XHTML/XML (e.g. '<' and '&') are replaced by the corresponding mnenonics (e.g. "&lt;" and "&amp;"). If flag 'convertNonASCII' is OFTrue, all characters < #32 and >= #127 are also converted (useful if only HTML 3.2 is supported which does not allow to specify the character set). In HTML 3.2 mode, the quotation mark (") is converted to "&#34;" instead of """ because the latter entity is not defined. In HTML mode, the apostrophe sign (') is converted to "&#39;" instead of "'" for the same reason.

Note
This method might create invalid character entity references, such as "&#27;" for ESC, if contained in the 'sourceString'. An XML document with such character entities cannot be parsed by most XML parsers. However, removing them from the output stream would also be no option.
Parameters
outstream used for the HTML/XHTML/XML mnenonic output
sourceStringsource string to be converted. May contain one or more NULL bytes.
convertNonASCIIconvert non-ASCII characters (< # 32 and >= #127) to numeric value (&#nnn;) if OFTrue. This might lead to invalid XML character entity references.
markupModeconvert to HTML, HTML 3.2, XHTML or XML markup. LF and CR are encoded as "&#10;" and "&#13;" in XML mode, the flag 'newlineAllowed' has no meaning in this case.
newlineAllowedoptional flag indicating whether newlines are allowed or not. If they are allowed, the text "<br>" (HTML) or "<br />" (XHTML) is used, "&para;" otherwise. The following combinations are accepted: LF, CR, LF CR, CF LF.
maxLengthmaximum number of characters from the source string to be converted. A value of 0 means all characters.
Returns
status, always returns EC_Normal

◆ convertToMarkupString()

static const OFString& OFStandard::convertToMarkupString ( const OFString sourceString,
OFString markupString,
const OFBool  convertNonASCII = OFFalse,
const E_MarkupMode  markupMode = MM_XML,
const OFBool  newlineAllowed = OFFalse,
const size_t  maxLength = 0 
)
static

convert character string to a HTML/XHTML/XML mnenonic string.

Characters with special meaning for HTML/XHTML/XML (e.g. '<' and '&') are replaced by the corresponding mnenonics (e.g. "&lt;" and "&amp;"). If flag 'convertNonASCII' is OFTrue, all characters < #32 and >= #127 are also converted (useful if only HTML 3.2 is supported which does not allow to specify the character set). In HTML 3.2 mode, the quotation mark (") is converted to "&#34;" instead of """ because the latter entity is not defined. In HTML mode, the apostrophe sign (') is converted to "&#39;" instead of "'" for the same reason.

Note
This method might create invalid character entity references, such as "&#27;" for ESC, if contained in the 'sourceString'. An XML document with such character entities cannot be parsed by most XML parsers. However, removing them from the 'markupString' would also be no option.
Parameters
sourceStringsource string to be converted. May also contain one or more NULL bytes.
markupStringreference to character string where the result should be stored
convertNonASCIIconvert non-ASCII characters (< # 32 and >= #127) to numeric value (&#nnn;) if OFTrue. This might lead to invalid XML character entity references.
markupModeconvert to HTML, HTML 3.2, XHTML or XML markup string. LF and CR are encoded as "@&@#10;" and "@&@#13;" in XML mode, the flag 'newlineAllowed' has no meaning in this case.
newlineAllowedoptional flag indicating whether newlines are allowed or not. If they are allowed, the text "<br>" (HTML) or "<br />" (XHTML) is used, "&para;" otherwise. The following combinations are accepted: LF, CR, LF CR, CF LF.
maxLengthmaximum number of characters from the source string to be converted. A value of 0 means all characters.
Returns
reference to resulting 'markupString' (might be empty if 'sourceString' was empty)

◆ convertToOctalStream()

static OFCondition OFStandard::convertToOctalStream ( STD_NAMESPACE ostream &  out,
const OFString sourceString,
const size_t  maxLength = 0 
)
static

convert character string to an octal format stream.

All non-ASCII and control characters (code < #32 and >= #127) are converted to their octal representation, i.e. to '\ooo' where 'ooo' are the three octal digits of the character. All other characters are output as is. See section 6.1.2.3 in DICOM PS 3.5.

Parameters
outstream used for the output
sourceStringsource string to be converted. May contain one or more NULL bytes.
maxLengthmaximum number of characters from the source string to be converted. A value of 0 means all characters.
Returns
status, always returns EC_Normal

◆ convertToOctalString()

static const OFString& OFStandard::convertToOctalString ( const OFString sourceString,
OFString octalString,
const size_t  maxLength = 0 
)
static

convert character string to an octal format string.

All non-ASCII and control characters (code < #32 and >= #127) are converted to their octal representation, i.e. to '\ooo' where 'ooo' are the three octal digits of the character. All other characters are output as is. See section 6.1.2.3 in DICOM PS 3.5.

Parameters
sourceStringsource string to be converted. May contain one or more NULL bytes.
octalStringreference to character string where the result should be stored
maxLengthmaximum number of characters from the source string to be converted. A value of 0 means all characters.
Returns
reference to resulting 'octalString' (might be empty if 'sourceString' was empty)

◆ copyFile()

static OFBool OFStandard::copyFile ( const OFFilename sourceFilename,
const OFFilename destFilename 
)
static

copy an existing file to a new file

Parameters
sourceFilenamename of the existing file (including directory) to be copied. This filename may contain wide characters if support enabled. Since there are various constructors for the OFFilename class, a "char *", "OFString" or "wchar_t *" can also be passed directly to this parameter.
destFilenamename of the new file (including directory) to be created as a copy. This filename may contain wide characters if support enabled. Since there are various constructors for the OFFilename class, a "char *", "OFString" or "wchar_t *" can also be passed directly to this parameter.
Returns
OFTrue if copying the file was successful, OFFalse otherwise. On most systems, the 'errno' variable is also set to a system-specific error code in case of failure.

◆ createDirectory()

static OFCondition OFStandard::createDirectory ( const OFFilename dirName,
const OFFilename rootDir 
)
static

create a directory (including sub-directories) if it does not yet exist.

In other words, this function creates directories recursively, i.e. with all sub-components.

Parameters
dirNamename of the directory to be created. This name may contain wide characters if support is enabled. Since there are various constructors for the OFFilename class, a "char *", "OFString" or "wchar_t *" can also be passed directly to this parameter.
rootDiroptional name of a root directory (prefix of 'dirName') that already exists and that can, therefore, be skipped during the creation of sub-directories. Should contain wide characters if and only if 'dirName' contains wide characters.
Returns
status, EC_Normal if successful (directory created or already exists), an error code otherwise

◆ decodeBase64()

static size_t OFStandard::decodeBase64 ( const OFString data,
unsigned char *&  result 
)
static

decode "Base64" encoded string.

Any character that does not belong to the Base64 alphabet (0..9, A..Z, a..z, + and /) is ignored when decoding the input string. This is especially true for line breaks which are usually contained in MIME (RFC 2045) encoded streams (see above). The first occurrence of a '=' character is taken as evidence that the end of the data has been reached. NB: The memory buffer in which the binary output is stored is allocated inside this function and has to to be freed (using "delete[]") by the caller! Do not pass a pointer to an already allocated buffer to this function, the caller does not know the exact size anyway.

Parameters
dataBase64 encoded input data (possibly padded with '=' at the end)
resultreceives pointer to resulting buffer with binary data (big endian encoded)
Returns
length of the resulting binary data (0 if an error occurred, in this case the buffer is deleted internally)

◆ deleteFile()

static OFBool OFStandard::deleteFile ( const OFFilename filename)
static

delete given file from filesystem

Parameters
filenamename of the file (including directory) to delete. This filename may contain wide characters if support enabled. Since there are various constructors for the OFFilename class, a "char *", "OFString" or "wchar_t *" can also be passed directly to this parameter.
Returns
OFTrue if deleting the file was successful, OFFalse otherwise. On most systems, the 'errno' variable is also set to a system-specific error code in case of failure.

◆ dirExists()

static OFBool OFStandard::dirExists ( const OFFilename dirName)
static

check whether the given directory exists.

This function also checks that the specified path points to directory and not to a file (or the like).

Parameters
dirNamename of the directory to be checked. This directory name may contain wide characters if support enabled. Since there are various constructors for the OFFilename class, a "char *", "OFString" or "wchar_t *" can also be passed directly to this parameter.
Returns
OFTrue if directory exists, OFFalse otherwise

◆ dropPrivileges()

static OFCondition OFStandard::dropPrivileges ( )
static

On Posix-like platform, this method executes setuid(getuid()), which causes the application to revert from root privileges to those of the calling user when the program is installed as setuid root.

DCMTK command line tools that open a socket for incoming DICOM network connections will call this method immediately after opening the socket. Since DICOM by default operates on port 104, which on Posix platforms requires root privileges to open, this ensures that the socket can be opened, yet operation continues with the (hopefully) limited rights of the calling user. On non-Posix platforms, this method does nothing and returns success.

Returns
success or failure. This method can fail if the kernel has been configured to only permit a certain number of processes to be created for each user, and the calling user already has the maximum number of processes running. In this case, the application should terminate since otherwise it would continue to run with full root privileges.

◆ encodeBase64() [1/2]

static const OFString& OFStandard::encodeBase64 ( const unsigned char *  data,
const size_t  length,
OFString result,
const size_t  width = 0 
)
static

encode binary data according to "Base64" as described in RFC 2045 (MIME).

Basic algorithm: groups of 3 bytes from the binary input are coded as groups of 4 bytes in the textual output. The input data is 'padded' with zeros to create a length that is an even multiple of 3. A special character ('=') is used to denote padding so that the output can be decoded back to its exact size. If the input data is NULL an empty string is returned.

Parameters
databuffer with binary data to be encoded (big endian required!)
lengthlength of the input data buffer (in bytes)
resultreference to resulting string variable (Base64 encoded)
widthmaximum number of characters per line in the output string (default: 0 = no line breaks, typical for MIME = 72)
Returns
reference to the resulting string

◆ encodeBase64() [2/2]

static OFCondition OFStandard::encodeBase64 ( STD_NAMESPACE ostream &  out,
const unsigned char *  data,
const size_t  length,
const size_t  width = 0 
)
static

encode binary data according to "Base64" as described in RFC 2045 (MIME).

Basic algorithm: groups of 3 bytes from the binary input are coded as groups of 4 bytes in the textual output. The input data is 'padded' with zeros to create a length that is an even multiple of 3. A special character ('=') is used to denote padding so that the output can be decoded back to its exact size. If the input data is NULL an error code (EC_IllegalParameter) is returned.

Parameters
outoutput stream used for the base64 encoded data
databuffer with binary data to be encoded (big endian required!)
lengthlength of the input data buffer (in bytes)
widthmaximum number of characters per line in the output stream (default: 0 = no line breaks, typical for MIME = 72)
Returns
status, EC_Normal if successful, an error code otherwise

◆ extractDigits()

template<typename T , size_t Count>
static T OFStandard::extractDigits ( const char *  )
static

extracts digits from a string and converts them to the given integer number type.

The result is similar to calling atoi, but extractDigits does not verify all characters are digits and does not require zero terminated strings. It is meant to be used in conjunction with OFStandard::checkDigits(). extractDigits does not handle sign characters ('+' and '-').

Template Parameters
Tthe type of the resulting value, e.g. unsigned int. Must be a valid integer type, i.e. OFnumeric_limits<T>::is_integer must be OFTrue.
Countthe number of digits to extract. Must be greater zero and less or equal to OFnumeric_limits<T>::digits10
stringa pointer to a character array to extract digits from.
Returns
a value of type T that is equivalent to the number represented by the digits.
Warning
The results are unspecified if the given string contains non-digit characters.

◆ fileExists()

static OFBool OFStandard::fileExists ( const OFFilename fileName)
static

check whether the given file exists.

This function also checks that the specified path points to file and not to a directory (or the like).

Parameters
fileNamename of the file to be checked. This filename may contain wide characters if support enabled. Since there are various constructors for the OFFilename class, a "char *", "OFString" or "wchar_t *" can also be passed directly to this parameter.
Returns
OFTrue if file exists, OFFalse otherwise

◆ forceSleep()

static void OFStandard::forceSleep ( Uint32  seconds)
static

Method that ensures that the current thread is actually sleeping for the defined number of seconds (at least).

The problem with the regular sleep() function called from OFStandard::sleep is that it might be interrupted by signals or a network timeout (depending on the operating system). This methods re-executes OFStandard's sleep method until the desired number of seconds have elapsed.

Parameters
secondsThe number of seconds to sleep (at least)

◆ ftoa()

static void OFStandard::ftoa ( char *  target,
size_t  targetSize,
double  value,
unsigned int  flags = 0,
int  width = 0,
int  precision = -1 
)
static

formats a floating-point number into an ASCII string.

This function works similar to sprintf(), except that this implementation is not affected by a locale setting. The radix character is always '.'. This implementation guarantees that the given string size is always respected by using strlcpy to copy the formatted string into the target buffer.

Note
The use of this implementation can be disabled by defining the macro DISABLE_OFSTD_FTOA at compile time; in this case, the locale dependent Posix implementation of sprintf is used and the application is responsible for making sure that the Posix locale is activated at all times.
Parameters
targetpointer to target string buffer
targetSizesize of target string buffer
valuedouble value to be formatted
flagsprocessing flags. Any of the flags defined below can be combined by bit-wise or.
widthwidth from format (%8d), or 0
precisionprecision from format (%.3d), or -1

◆ getAddressByHostname()

static void OFStandard::getAddressByHostname ( const char *  name,
OFSockAddr result 
)
static

This function performs a DNS lookup of an IP address based on a hostname.

If a DNS lookup yields multiple IP addresses, only the first one is returned.

Parameters
namehostname
resulta OFSockAddr instance in which the result is stored

◆ getDirNameFromPath() [1/2]

static OFFilename& OFStandard::getDirNameFromPath ( OFFilename result,
const OFFilename pathName,
const OFBool  assumeDirName = OFTrue 
)
static

get directory name component from given path name.

Extracts the substring before the last path separator. If there is no path separator in the given path name, the value of 'pathName' is returned by default; if 'assumeDirName' is OFFalse, an empty string is returned. NB: This function neither checks whether the given 'pathName' exists nor whether the resulting name points to a valid or existing directory.

Parameters
resultstring variable in which the resulting directory name is stored. This name may contain wide characters if support is enabled and 'pathName' contains wide characters. In any case, the resulting string is stored with UTF-8 encoding (8-bit) as an alternative representation.
pathNamepath name from which the directory name should be extracted. This name may contain wide characters if support is enabled. Since there are various constructors for the OFFilename class, a "char *", "OFString" or "wchar_t *" can also be passed directly to this parameter.
assumeDirNameassume that there always is a directory name in 'pathName'
Returns
reference to the resulting directory name (same as 'result')

◆ getDirNameFromPath() [2/2]

static OFString& OFStandard::getDirNameFromPath ( OFString result,
const OFString pathName,
const OFBool  assumeDirName = OFTrue 
)
static

get directory name component from given path name.

Extracts the substring before the last path separator. If there is no path separator in the given path name, the value of 'pathName' is returned by default; if 'assumeDirName' is OFFalse, an empty string is returned. NB: This function neither checks whether the given 'pathName' exists nor whether the resulting name points to a valid or existing directory.

Note
This method is provided for reasons of backward compatibility. Internally, the following method (OFFilename version) is used.
Parameters
resultstring variable in which the resulting directory name is stored
pathNamepath name from which the directory name should be extracted
assumeDirNameassume that there always is a directory name in 'pathName'
Returns
reference to the resulting directory name (same as 'result')

◆ getFilenameFromPath() [1/2]

static OFFilename& OFStandard::getFilenameFromPath ( OFFilename result,
const OFFilename pathName,
const OFBool  assumeFilename = OFTrue 
)
static

get file name component from given path name.

Extracts the substring after the last path separator. If there is no path separator in the given path name, the value of 'pathName' is returned by default; if 'assumeFilename' is OFFalse, an empty string is returned. NB: This function neither checks whether the given 'pathName' exists nor whether the resulting name points to a valid or existing file.

Parameters
resultstring variable in which the resulting file name is stored. This name may contain wide characters if support is enabled and 'pathName' contains wide characters. In any case, the resulting string is stored with UTF-8 encoding (8-bit) as an alternative representation.
pathNamepath name from which the file name should be extracted. This name may contain wide characters if support is enabled. Since there are various constructors for the OFFilename class, a "char *", "OFString" or "wchar_t *" can also be passed directly to this parameter.
assumeFilenameassume that there always is a file name in 'pathName'
Returns
reference to the resulting file name (same as 'result')

◆ getFilenameFromPath() [2/2]

static OFString& OFStandard::getFilenameFromPath ( OFString result,
const OFString pathName,
const OFBool  assumeFilename = OFTrue 
)
static

get file name component from given path name.

Extracts the substring after the last path separator. If there is no path separator in the given path name, the value of 'pathName' is returned by default; if 'assumeFilename' is OFFalse, an empty string is returned. NB: This function neither checks whether the given 'pathName' exists nor whether the resulting name points to a valid or existing file.

Note
This method is provided for reasons of backward compatibility. Internally, the following method (OFFilename version) is used.
Parameters
resultstring variable in which the resulting file name is stored
pathNamepath name from which the file name should be extracted
assumeFilenameassume that there always is a file name in 'pathName'
Returns
reference to the resulting file name (same as 'result')

◆ getFileSize()

static size_t OFStandard::getFileSize ( const OFFilename filename)
static

determine size of given file (in bytes)

Parameters
filenamename of the file to be checked. This filename may contain wide characters if support enabled. Since there are various constructors for the OFFilename class, a "char *", "OFString" or "wchar_t *" can also be passed directly to this parameter.
Returns
size of the file in bytes (0 in case of error)

◆ getGrNam()

static OFGroup OFStandard::getGrNam ( const char *  name)
static

Thread-safe version of getgrnam.

Parameters
namethe group name.
Returns
a OFStandard::OFGroup object.

◆ getHostName()

static OFString OFStandard::getHostName ( )
static

Retrieve the local domain name, e.

g. 'localhost'.

Returns
the host name as an OFString value.

◆ getHostnameByAddress()

static OFString OFStandard::getHostnameByAddress ( const char *  addr,
int  len,
int  type 
)
static

This function performs a reverse DNS lookup of a hostname.

The parameters are identical to those passed to gethostbyaddr(). If the lookup fails, an empty string is returned.

Parameters
addrIP address, actually a pointer to a struct in_addr or a struct in6_addr object
lenlength of the struct pointed to by addr
typeaddress type, either AF_INET or AF_INET6
Returns
hostname for the IP address

◆ getLastNetworkErrorCode()

static OFerror_code OFStandard::getLastNetworkErrorCode ( )
static

Retrieve the last network specific error code that was emitted in the calling thread.

The current implementation uses errno on POSIX-like platforms and WSAGetLastError() on Windows.

Returns
the last error code as OFerror_code object.

◆ getLastSystemErrorCode()

static OFerror_code OFStandard::getLastSystemErrorCode ( )
static

Retrieve the last operating system error code that was emitted in the calling thread.

The current implementation uses errno on POSIX-like platforms and GetLastError() on Windows.

Returns
the last error code as OFerror_code object.

◆ getProcessID()

static long OFStandard::getProcessID ( )
static

Determines the identification of the running process.

Returns
the process ID of the currently running process.

◆ getPwNam()

static OFPasswd OFStandard::getPwNam ( const char *  name)
static

Thread-safe version of getpwnam.

Parameters
namethe username.
Returns
a OFStandard::OFPasswd object.

◆ getUserName()

static OFString OFStandard::getUserName ( )
static

Retrieve the name of the user that started the current process.

Returns
the user name as an OFString value.

◆ initializeNetwork()

static void OFStandard::initializeNetwork ( )
static

Initialize the network API (if necessary), e.g. Winsock.

Calls the appropriate network initialization routines for the current platform, e.g. WSAStartup().

Note
This function must be called by an application before any network related functions are used, be it listening on a socket or just retrieving the current host name. Not all platforms require calling a network initialization routine, therefore testing if it works to determine if this method must be called is not an option – just always ensure to call it at program startup if the application does something network related!

◆ isReadable()

static OFBool OFStandard::isReadable ( const OFFilename pathName)
static

check whether the given path is readable.

This function works for both files and directories.

Parameters
pathNamename of the path to be checked. This path name may contain wide characters if support enabled. Since there are various constructors for the OFFilename class, a "char *", "OFString" or "wchar_t *" can also be passed directly to this parameter.
Returns
OFTrue if path is readable, OFFalse otherwise

◆ isWriteable()

static OFBool OFStandard::isWriteable ( const OFFilename pathName)
static

check whether the given path is writeable.

This function works for both files and directories.

Parameters
pathNamename of the path to be checked. This path name may contain wide characters if support enabled. Since there are various constructors for the OFFilename class, a "char *", "OFString" or "wchar_t *" can also be passed directly to this parameter.
Returns
OFTrue if path is writeable, OFFalse otherwise

◆ milliSleep()

static void OFStandard::milliSleep ( unsigned int  millisecs)
static

makes the current process sleep until the given number of milliseconds have elapsed or a signal which is not ignored arrives

Parameters
millisecsnumber of milliseconds to sleep

◆ my_sleep()

static unsigned int OFStandard::my_sleep ( unsigned int  seconds)
staticprivate

makes the current process sleep until seconds seconds have elapsed or a signal arrives which is not ignored

Parameters
secondsnumber of seconds to sleep
Returns
zero if the requested time has elapsed, or the number of seconds left to sleep

◆ my_strlcat()

static size_t OFStandard::my_strlcat ( char *  dst,
const char *  src,
size_t  siz 
)
staticprivate

private implementation of strlcat.

Called when strlcat is not available in the standard library.

Parameters
dstdestination buffer of size siz, must not be NULL
srcsource string, must not be NULL
sizsize of destination buffer
Returns
the total length of the string the function tried to create, i.e. the initial length of dst plus the length of src

◆ my_strlcpy()

static size_t OFStandard::my_strlcpy ( char *  dst,
const char *  src,
size_t  siz 
)
staticprivate

private implementation of strlcpy.

Called when strlcpy is not available in the standard library.

Parameters
dstdestination buffer of size siz, must not be NULL
srcsource string, must not be NULL
sizsize of destination buffer
Returns
the total length of the string the function tried to create, i.e. strlen(src)

◆ normalizeDirName() [1/2]

static OFFilename& OFStandard::normalizeDirName ( OFFilename result,
const OFFilename dirName,
const OFBool  allowEmptyDirName = OFFalse 
)
static

normalize the given directory name.

Removes trailing path separators from the directory name. If the resulting directory name is an empty string and the flag 'allowEmptyDirName' is OFFalse the directory name is set to "." (current directory). If the resulting directory name is "." and the flag 'allowEmptyDirName' is OFTrue the directory name is set to an empty string.

Parameters
resultstring variable in which the resulting directory name is stored. This name may contain wide characters if support is enabled and 'dirName' contains wide characters. In any case, the resulting string is stored with UTF-8 encoding (8-bit) as an alternative representation.
dirNamedirectory name to be normalized. This name may contain wide characters if support is enabled. Since there are various constructors for the OFFilename class, a "char *", "OFString" or "wchar_t *" can also be passed directly to this parameter.
allowEmptyDirNameflag indicating whether an empty directory name is allowed
Returns
reference to the resulting directory name (same as 'result')

◆ normalizeDirName() [2/2]

static OFString& OFStandard::normalizeDirName ( OFString result,
const OFString dirName,
const OFBool  allowEmptyDirName = OFFalse 
)
static

normalize the given directory name.

Removes trailing path separators from the directory name. If the resulting directory name is an empty string and the flag 'allowEmptyDirName' is OFFalse the directory name is set to "." (current directory). If the resulting directory name is "." and the flag 'allowEmptyDirName' is OFTrue the directory name is set to an empty string.

Note
This method is provided for reasons of backward compatibility. Internally, the following method (OFFilename version) is used.
Parameters
resultstring variable in which the resulting directory name is stored
dirNamedirectory name to be normalized
allowEmptyDirNameflag indicating whether an empty directory name is allowed
Returns
reference to the resulting directory name (same as 'result')

◆ pathExists()

static OFBool OFStandard::pathExists ( const OFFilename pathName)
static

check whether the given path exists.

This function does not distinguish files from directories (use 'fileExists()' or 'directoryExists()' if required).

Parameters
pathNamename of the path to be checked. This path name may contain wide characters if support enabled. Since there are various constructors for the OFFilename class, a "char *", "OFString" or "wchar_t *" can also be passed directly to this parameter.
Returns
OFTrue if path exists, OFFalse otherwise

◆ removeRootDirFromPathname()

static OFCondition OFStandard::removeRootDirFromPathname ( OFFilename result,
const OFFilename rootDir,
const OFFilename pathName,
const OFBool  allowLeadingPathSeparator = OFTrue 
)
static

remove root directory prefix from given path name.

In case 'pathName' starts with 'rootDir', the common prefix is removed. Otherwise, an empty string is returned (or a cleared OFFilename in case of error).

Parameters
resultstring variable in which the resulting path name is stored. This name may contain wide characters if support is enabled and 'rootDir' as well as 'pathName' contain wide characters. In any case, the resulting string is stored with UTF-8 encoding (8-bit) as an alternative representation.
rootDirname of the root directory to be removed. This name may contain wide characters if support is enabled. Since there are various constructors for the OFFilename class, a "char *", "OFString" or "wchar_t *" can also be passed directly to this parameter.
pathNamepath name from which the root directory (prefix) is removed. Should contain wide characters if and only if 'rootDir' contains wide characters.
allowLeadingPathSeparatorflag indicating whether a leading path separator is allowed for the resulting path name (automatically removed otherwise)
Returns
status, EC_Normal if successful, an error code otherwise

◆ renameFile()

static OFBool OFStandard::renameFile ( const OFFilename oldFilename,
const OFFilename newFilename 
)
static

change name of a given file

Parameters
oldFilenamecurrent name of the file (including directory) to be renamed. This filename may contain wide characters if support enabled. Since there are various constructors for the OFFilename class, a "char *", "OFString" or "wchar_t *" can also be passed directly to this parameter.
newFilenamenew name of the file (including directory), i.e. after renaming. Should contain wide characters if and only if 'oldFilename' contains wide characters.
Returns
OFTrue if changing the name was successful, OFFalse otherwise. On most systems, the 'errno' variable is also set to a system-specific error code in case of failure.

◆ safeAdd()

template<typename T >
static OFBool OFStandard::safeAdd ( a,
b,
T &  sum 
)
inlinestatic

check whether addition is safe (i.e. no overflow occurs) and if so, perform it (i.e. compute a+b=sum).

Only works for unsigned types.

Parameters
afirst number to add
bsecond number to add
sumresulting sum of both numbers, if addition is safe, otherwise parameter value is not touched by the function
Returns
OFTrue if addition is safe and could be performed, OFFalse otherwise

◆ safeMult()

template<typename T >
static OFBool OFStandard::safeMult ( a,
b,
T &  product 
)
inlinestatic

check whether multiplication is safe (i.e. no overflow occurs) and if so, perform it (i.e. compute a*b=product).

Only works for unsigned types.

Parameters
afirst number to multiply
bsecond number to multiply
productresulting product of both numbers, if multiplication is safe, otherwise parameter value is not touched by the function
Returns
OFTrue if multiplication is safe and could be performed, OFFalse otherwise

◆ safeSubtract()

template<typename T >
static OFBool OFStandard::safeSubtract ( minuend,
subtrahend,
T &  difference 
)
inlinestatic

check whether subtraction is safe (i.e. no underflow occurs) and if so, perform it (i.e. compute minuend-subtrahend=difference).

Only works for unsigned types.

Parameters
minuendnumber to subtract from
subtrahendnumber to subtract from minuend
differencedifference, if subtraction is safe, otherwise the parameter value is not touched by the function
Returns
OFTrue if subtraction is safe and could be performed, OFFalse otherwise

◆ searchDirectoryRecursively() [1/2]

static size_t OFStandard::searchDirectoryRecursively ( const OFFilename directory,
OFList< OFFilename > &  fileList,
const OFFilename pattern,
const OFFilename dirPrefix,
const OFBool  recurse = OFTrue 
)
static

scan a given directory (recursively) and add all filenames found to a list

Parameters
directoryname of the directory to be scanned. This name may contain wide characters if support is enabled. Since there are various constructors for the OFFilename class, a "char *", "OFString" or "wchar_t *" can also be passed directly to this parameter.
fileListlist to which the filenames are added. These names may contain wide characters if support is enabled and 'directory' contains wide characters. In any case, the resulting string is stored with UTF-8 encoding (8-bit) as an alternative representation. Please note that the list is not not cleared automatically before new entries are added.
patternwildcard pattern used to match the filenames against. Should contain wide characters if and only if 'directory' contains wide characters. An empty pattern matches all files. In order to work under Unix the system function fnmatch() is required.
dirPrefixprefix added to the directory name. Should contain wide characters if and only if 'directory' contains wide characters. This prefix will, however, not be part of the filenames added to the list.
recurseflag indicating whether to search recursively (default) or not
Returns
number of new files added to the list

◆ searchDirectoryRecursively() [2/2]

static size_t OFStandard::searchDirectoryRecursively ( const OFString directory,
OFList< OFString > &  fileList,
const OFString pattern = "",
const OFString dirPrefix = "",
const OFBool  recurse = OFTrue 
)
static

scan a given directory (recursively) and add all filenames found to a list

Note
This method is provided for reasons of backward compatibility. Internally, the following method (OFFilename version) is used.
Parameters
directoryname of the directory to be scanned
fileListlist to which the filenames are added. Please note that the list is not not cleared automatically before new entries are added.
patternoptional wildcard pattern used to match the filenames against. By default all files match. In order to work under Unix the system function fnmatch() is required.
dirPrefixoptional prefix added to the directory name. This prefix will, however, not be part of the filenames added to the list.
recurseflag indicating whether to search recursively (default) or not
Returns
number of new files added to the list

◆ shutdownNetwork()

static void OFStandard::shutdownNetwork ( )
static

Shutdown the network API (if necessary), e.g. Winsock.

Calls the appropriate network shutdown routines to free used resources (e.g. WSACleanup()).

◆ sleep()

static unsigned int OFStandard::sleep ( unsigned int  seconds)
inlinestatic

makes the current process sleep until seconds seconds have elapsed or a signal arrives which is not ignored

Parameters
secondsnumber of seconds to sleep
Returns
zero if the requested time has elapsed, or the number of seconds left to sleep

◆ snprintf()

static int OFStandard::snprintf ( char *  str,
size_t  size,
const char *  format,
  ... 
)
static

Standard C99 formatted string output function.

This is an implementation of the snprintf(3) function as defined in the C99 standard. Like all functions of the printf() family, it produces output according to a format string. Output is written to the character array passed as parameter str. The function never writes more than size bytes and guarantees that the result will be NUL terminated, although it may be truncated if the buffer provided is too small.

Parameters
strstring buffer to write to
sizesize of string buffer, in bytes
formatprintf() format string
...parameters to be formatted
Returns
number of characters that have been written (if the buffer is large enough) or the number of characters that would have been written (if the buffer is too small), in both cases not including the final NUL character.

◆ strerror()

static const char* OFStandard::strerror ( const int  errnum,
char *  buf,
const size_t  buflen 
)
static

convert a given error code to a string.

This function wraps the various approaches found on different systems. Internally, the standard function strerror() or strerror_r() is used.

Parameters
errnumerror code to be converted
bufbuffer which is used to store the result string (if supported)
buflensize if the buffer in bytes
Returns
pointer to string describing the error code. Please note that depending on the implementation of the function used, the result may or may not be a pointer to buf. The return value can also be NULL if the buffer is invalid.

Referenced by OFFile::getLastErrorString().

◆ strlcat()

static size_t OFStandard::strlcat ( char *  dst,
const char *  src,
size_t  siz 
)
inlinestatic

This function appends the NUL-terminated string src to the end of dst.

It will append at most size - strlen(dst) - 1 bytes, NUL- terminating the result. It is designed to be a safer, more consistent, and less error-prone replacement for strncat(3). strlcat takes the full size of the buffer (not just the length) and guarantees to NUL-terminate the result (as long as size is larger than 0). Note that you should include a byte for the NUL in size. Also note that strlcat only operates on true C strings, i. e. dst and src must be NUL-terminated.

Parameters
dstdestination buffer of size siz, must not be NULL
srcsource string, must not be NULL
sizsize of destination buffer
Returns
the total length of the string the function tried to create, i.e. the initial length of dst plus the length of src. While this may seem somewhat confusing it was done to make truncation detection simple.

◆ strlcpy()

static size_t OFStandard::strlcpy ( char *  dst,
const char *  src,
size_t  siz 
)
inlinestatic

This function copies up to size - 1 characters from the NUL- terminated string src to dst, NUL-terminating the result.

It is designed to be a safer, more consistent, and less error-prone replacement for strncpy(3). strlcpy takes the full size of the buffer (not just the length) and guarantees to NUL-terminate the result (as long as size is larger than 0). Note that you should include a byte for the NUL in size. Also note that strlcpy only operates on true C strings, i. e. src must be NUL-terminated.

Parameters
dstdestination buffer of size siz, must not be NULL
srcsource string, must not be NULL
sizsize of destination buffer
Returns
the total length of the string the function tried to create, i.e. strlen(src). While this may seem somewhat confusing it was done to make truncation detection simple.

◆ toLower() [1/2]

static OFString& OFStandard::toLower ( OFString result,
const OFString value 
)
static

returns the lower-case version of a given string

Parameters
resultstring variable in which the result is stored
valuestring value to be converted to lower case
Returns
reference to the resulting string (same as 'result')

◆ toLower() [2/2]

static OFString& OFStandard::toLower ( OFString value)
static

returns the lower-case version of a given string.

NB: This function changes the parameter 'value'.

Parameters
valuestring value to be converted to lower case
Returns
reference to the resulting string (same as 'value')

◆ toUpper() [1/2]

static OFString& OFStandard::toUpper ( OFString result,
const OFString value 
)
static

returns the upper-case version of a given string

Parameters
resultstring variable in which the result is stored
valuestring value to be converted to upper case
Returns
reference to the resulting string (same as 'result')

◆ toUpper() [2/2]

static OFString& OFStandard::toUpper ( OFString value)
static

returns the upper-case version of a given string.

NB: This function changes the parameter 'value'.

Parameters
valuestring value to be converted to upper case
Returns
reference to the resulting string (same as 'value')

◆ trimString() [1/2]

static void OFStandard::trimString ( const char *&  pBegin,
const char *&  pEnd 
)
static

An utility function that finds a substring within a string that does not contain leading and trailing spaces and null bytes, effectively trimming the string without unnecessary copies.

Parameters
pBegina reference to a pointer to the beginning of the string.
pEnda reference to a pointer to the end of the string (the first byte behind the string).
Precondition
pBegin <= pEnd

trimString() increments pBegin and decrements pEnd until either both point to a non-null and non-space character (the position after it in case of pEnd) or both become equal (in case the string only contains spaces and null bytes).

◆ trimString() [2/2]

static void OFStandard::trimString ( const char *&  str,
size_t &  size 
)
static

An utility function that finds a substring within a string that does not contain leading and trailing spaces and null bytes, effectively trimming the string without unnecessary copies.

Parameters
stra reference to a pointer to the beginning of the string.
sizea reference to a size_t variable containing the number of bytes in the string referenced by str.

This overload is implemented using the other overload of the function operating on two character pointers.

◆ vsnprintf()

static int OFStandard::vsnprintf ( char *  str,
size_t  size,
const char *  format,
va_list  ap 
)
static

Standard C99 formatted string output function.

This is an implementation of the snprintf(3) function as defined in the C99 standard. Like all functions of the printf() family, it produces output according to a format string. Output is written to the character array passed as parameter str. The function never writes more than size bytes and guarantees that the result will be NUL terminated, although it may be truncated if the buffer provided is too small.

Parameters
strstring buffer to write to
sizesize of string buffer, in bytes
formatprintf() format string
apparameters to be formatted
Returns
number of characters that have been written (if the buffer is large enough) or the number of characters that would have been written (if the buffer is too small), in both cases not including the final NUL character.

Member Data Documentation

◆ ftoa_alternate

const unsigned int OFStandard::ftoa_alternate
static

convert value to alternate form.

The result will always contain a decimal point, even if no digits follow the point. For g and G conversions, trailing zeroes will not be removed from the result.


The documentation for this class was generated from the following file:


Generated on Thu Apr 28 2022 for DCMTK Version 3.6.7 by Doxygen 1.9.1