Module Description

Special formatting (e.g DataSizeStr()), et cetera...

Macros
#define	HASH_STRING_ALGORITHM_DEFAULT (0)

#define	HASH_STRING_ALGORITHM_X65599 (1)

#define	HASH_STRING_ALGORITHM_INVALID (0xffffffff)

#define	DEF_DATETIME_FMT _T("%Y-%m-%d %H.%M.%S")

Functions
bool	SplitUncPath (IN CSTR UncPath, OUT TSTR Svr, UINT ccSvr, OUT TSTR Share, UINT ccShare, OPTOUT TSTR Path=NULL, UINT ccPath=0)

bool	SplitNetShareName (IN CSTR ShareName, OUT WSTR Server, UINT ccServer, OUT WSTR Share, UINT ccShare)

CSTR	WithoutBackslash (CSTR PathName)

CSTR	WithBackslash (CSTR PathName)

bool	GetRootOf (IN CSTR PathName, OUT TSTR Root, UINT ccRoot)

CSTR __cdecl	StrFmt (TSTR Buf, UINT ccBuf, CSTR Fmt,...)

TSTR	ReplaceStrChar (TSTR Str, TCHAR From, TCHAR To, OPTOUT UINT *pCount)

bool	MatchPattern (CSTR String, CSTR Pattern, bool CaseSens)

UINT	DeduplicateCharSepText (INOUT ASTR Text, CHAR Separator, bool caseSens, bool emitSorted)

UINT	PrependString (INOUT TSTR String, UINT ccBuf, OPTIN TCHAR Sep, CSTR Prolog)

UINT	AppendString (INOUT TSTR String, UINT ccBuf, OPTIN TCHAR Sep, CSTR Epilog)

ULONG	GetStringHash (WCSTR Str, ULONG Algorithm=0, bool caseSens=true)

CSTR	HexString (PBYTE pData, UINT dataLen, TSTR strBuf=NULL, UINT bufSize=0, bool tailDots=false)

CSTR	DataSizeStr (UINT64 Size)

CSTR	IsoDataSizeStr (UINT64 Size)

CSTR	FileAttribStr (DWORD Attr)

CSTR	FileTimeStr (FILETIME *FTime, CSTR Fmt=_T("%Y-%m-%d %H.%M.%S"))

CSTR	SysTimeStr (SYSTEMTIME *Time, CSTR Fmt)

CSTR	FileTypeStr (CSTR FName)

CSTR	EngFormat (long double Value, BYTE nDecimals, CSTR Unit=NULL)

Macro Definition Documentation

◆ HASH_STRING_ALGORITHM_DEFAULT

#define HASH_STRING_ALGORITHM_DEFAULT (0)

Definition at line 435 of file StrFunc.h.

◆ HASH_STRING_ALGORITHM_X65599

#define HASH_STRING_ALGORITHM_X65599 (1)

Definition at line 436 of file StrFunc.h.

◆ HASH_STRING_ALGORITHM_INVALID

#define HASH_STRING_ALGORITHM_INVALID (0xffffffff)

Definition at line 437 of file StrFunc.h.

◆ DEF_DATETIME_FMT

#define DEF_DATETIME_FMT _T("%Y-%m-%d %H.%M.%S")

Default date/time format used by FileTimeStr().
Output fmt = yyyy-mm-dd hh.mm.ss

Definition at line 478 of file StrFunc.h.

Function Documentation

◆ SplitUncPath()

bool SplitUncPath	(	IN CSTR	UncPath,
		OUT TSTR	Svr,
		UINT	ccSvr,
		OUT TSTR	Share,
		UINT	ccShare,
		OPTOUT TSTR	Path = `NULL`,
		UINT	ccPath = `0`
	)

SplitUncPath() separates an UNC path into it's constituent parts.

Parameters

UncPath	An UNC entity. Must contain at least server and share components. Any prefixes (e.g "\\?\UNC\") are discarded. NT device paths produce undefined results.
Svr	Buffer that recieves the server name. ccSvr is it's length, in TCHARs.
Share	Svr Buffer that recieves the share name. ccShare is it's length.
Path	[optional] Buffer that recieves the path component, if any.

Returns: Returns true if arguments are ok and UncPath contain server and share. If UncPath is ill formed, or Svr or Share is NULL, the error is ERROR_INVALID_PARAMETER.
If ccSvr, ccShare, or ccPath is too small, the error is ERROR_INSUFFICIENT_BUFFER.

◆ SplitNetShareName()

bool SplitNetShareName	(	IN CSTR	ShareName,
		OUT WSTR	Server,
		UINT	ccServer,
		OUT WSTR	Share,
		UINT	ccShare
	)

SplitNetShareName() extracts Server and Share names suitable for LM calls.

Parameters

ShareName	A transmutable UNC "\\Server\Share" specification.
Server,Share	Wide-string buffers recieving the components, directly suitable for calls to e.g. NetShareGetInfo().

See also: SplitUncPath()

Definition at line 634 of file StrFunc.cpp.

◆ WithoutBackslash()

CSTR WithoutBackslash ( CSTR PathName )

If PathName has a trailing backslash, the string is copied to a MAX_PATH
thread-local buffer, the backslash removed, and the modified string returned,
otherwise PathName is returned verbatim. See also WithBackslash().

Definition at line 668 of file StrFunc.cpp.

◆ WithBackslash()

CSTR WithBackslash ( CSTR PathName )

See WithoutBackslash().

Definition at line 682 of file StrFunc.cpp.

◆ GetRootOf()

bool GetRootOf	(	IN CSTR	PathName,
		OUT TSTR	Root,
		UINT	ccRoot
	)

[preliminary] Get the root component of PathName.
It may be an X:\ DOS volume or a UNC \Server\Share.
Any path prefix in PathName is discarded from the result.
Note: UNC paths w/o leading \ and NT device paths produce undefined results.

Definition at line 661 of file StrFunc.cpp.

◆ StrFmt()

CSTR __cdecl StrFmt	(	TSTR	Buf,
		UINT	ccBuf,
		CSTR	Fmt,
			...
	)

StrFmt() uses _vstprintf_s() to format the text, and returns the buffer.
If Buf == NULL and ccBuf == 0, an internal static MAX_PATH buffer is used.
If Buf == NULL and ccBuf != 0, a buffer is allocated with newStrBuf().
If Buf != NULL, then it and ccBuf are used verbatim.

Definition at line 545 of file StrFunc.cpp.

◆ ReplaceStrChar()

TSTR ReplaceStrChar	(	TSTR	Str,
		TCHAR	From,
		TCHAR	To,
		OPTOUT UINT *	pCount
	)

ReplaceStrChar() replaces all ocurrences of From with To.
It returns a pointer to the terminating null char in Str.
Optionally it returns nr of chars replaced, in *pCount.

Definition at line 699 of file StrFunc.cpp.

◆ MatchPattern()

bool MatchPattern	(	CSTR	String,
		CSTR	Pattern,
		bool	CaseSens
	)

Wildcard pattern match, including char set matching (e.g. [aex-z]).
If CaseSens is false, char sets are also treated as case insensitive.

Parameters

String	The text to analyze.
Pattern	A wildcard pattern to look for in String. The pattern may include one or more *, ?, and char sets (e.g. [ax-z]).
CaseSens	True if the matching should be case sensitive. If CaseSens if false, char sets will also be treated as case insensitive.

Definition at line 743 of file StrFunc.cpp.

◆ DeduplicateCharSepText()

UINT DeduplicateCharSepText	(	INOUT ASTR	Text,
		CHAR	Separator,
		bool	caseSens,
		bool	emitSorted
	)

DeduplicateCharSepText() removes duplicate entries from a char separated list.

Parameters

Text	Buffer containing the text to be culled. Note: The buffer must have room for one extra char at the Text end, due to temporary in-place conversion to multi-sz.
Separator	Separator char in Text, f.ex. SEMICOLON or COMMA.
caseSens	Specify whether the comparator should be case sensitive or not.
emitSorted	Specify whether the result should be sorted or not.

The function returns the length of the culled text, or zero on failure.
Note: This function is currently not available in _UNICODE builds.

◆ PrependString()

UINT PrependString	(	INOUT TSTR	String,
		UINT	ccBuf,
		OPTIN TCHAR	Sep,
		CSTR	Prolog
	)

PrependString() prepends a string in-place.

Parameters

String	Buffer containing the text to be prepended.
ccBuf	Length of the buffer, in TCHARs.
Sep	Optional separator char to insert (0 == none).
Prolog	The text to precede the current buffer content.

◆ AppendString()

UINT AppendString	(	INOUT TSTR	String,
		UINT	ccBuf,
		OPTIN TCHAR	Sep,
		CSTR	Epilog
	)

AppendString() appends a string in-place.
See PrependString() for parameter details.

◆ GetStringHash()

ULONG GetStringHash	(	WCSTR	Str,
		ULONG	Algorithm = `0`,
		bool	caseSens = `true`
	)

GetStringHash() provides a handy wrap for RtlHashUnicodeString().

Definition at line 947 of file StrFunc.cpp.

◆ HexString()

CSTR HexString	(	PBYTE	pData,
		UINT	dataLen,
		TSTR	strBuf = `NULL`,
		UINT	bufSize = `0`,
		bool	tailDots = `false`
	)

HexString() builds a readable hex string from the given data.
If strBuf is NULL or bufSize is zero, a static buffer of MAX_PATH is used.

Definition at line 981 of file StrFunc.cpp.

◆ DataSizeStr()

CSTR DataSizeStr ( UINT64 Size )

DataSizeStr() returns e.g. "2.3 MB" (B,kB,MB,GB,TB,PB,EB,ZB,YB).
Note: Uses an internal static buffer.

Definition at line 1042 of file StrFunc.cpp.

◆ IsoDataSizeStr()

CSTR IsoDataSizeStr ( UINT64 Size )

IsoDataSizeStr() returns e.g. "2.2 MiB" (B,kiB,MiB,GiB,TiB,PiB,EiB,ZiB,YiB).
Note: Uses an internal static buffer.

Definition at line 1066 of file StrFunc.cpp.

◆ FileAttribStr()

CSTR FileAttribStr ( DWORD Attr )

FileAttribStr() returns all of the applicable [DAHRSCEOPZT], or a blank string.

D: Directory
A: Archive
H: Hidden
R: ReadOnly
S: System
C: Compressed
E: Encrypted
O: OffLine
P: ReparsePoint
Z: Sparse
T: Temporary
Note: Uses an internal static buffer.

Definition at line 1092 of file StrFunc.cpp.

◆ FileTimeStr()

CSTR FileTimeStr	(	FILETIME *	FTime,
		CSTR	Fmt = `_T("%Y-%m-%d %H.%M.%S")`
	)

FileTimeStr() returns a formatted file time string. See SysTimeStr().

Definition at line 1124 of file StrFunc.cpp.

◆ SysTimeStr()

CSTR SysTimeStr	(	SYSTEMTIME *	Time,
		CSTR	Fmt
	)

SysTimeStr() formats a SYSTEMTIME into a human readable string with strftime().
Note that time zone reports the current system locale since Time doesn't have one.

Parameters

Fmt

Formatting specifications for strftime() / wcsftime().

%a Abbreviated weekday name
%A Full weekday name
%b Abbreviated month name
%B Full month name
%c Date and time representation appropriate for locale
%d Day of month as decimal number (01..31)
%H Hour in 24-hour format (00..23)
%I Hour in 12-hour format (01..12)
%j Day of year as decimal number (001..366)
%m Month as decimal number (01..12)
%M Minute as decimal number (00..59)
%p Current locales A.M./P.M. indicator for 12-hour clock
%S Second as decimal number (00..59)
%U Week of year as decimal number, with Sunday as first day of week (00..53)
%w Weekday as decimal number (0..6; Sunday is 0)
%W Week of year as decimal number, with Monday as first day of week (00..53)
%x Date representation for current locale
%X Time representation for current locale
%y Year without century, as decimal number (00..99)
%Y Year with century, as decimal number
%z,%Z Time-zone name or abbreviation; no characters if time zone is unknown
%% Percent sign

Returns: If an error occurs (eg. buffer overflow) the return is an empty string.
Note: The function uses an internal static buffer.

Definition at line 1131 of file StrFunc.cpp.

◆ FileTypeStr()

CSTR FileTypeStr ( CSTR FName )

FileTypeStr() gets a file type string from the shell.

Note: If you call FileTypeStr repeatedly, you should call InitShellFunc()
before the first call. Not doing so will result in poor performance, since it would
force FileTypeStr to call InitShellFunc() and DoneShellFunc() each time.

The function uses an internal static buffer of 80 chars.

Definition at line 1151 of file StrFunc.cpp.

◆ EngFormat()

CSTR EngFormat	(	long double	Value,
		BYTE	nDecimals,
		CSTR	Unit = `NULL`
	)

EngFormat() formats a value with a scientific/engineering SI prefix unit.

The output format is f.ex. "12.345 kHz", formatted into an internal static buffer.

Parameters

nDecimals	Nr of decimals to output.
Unit	Optional suffix to append to output, e.g. "Hz".

Note: The function uses an internal static buffer of 50 chars.

Unit prefix list

10^24 yotta Y
10^21 zetta Z
10^18 exa E
10^15 peta P
10^12 tera T
10^9 giga G
10^6 mega M
10^3 kilo k
#10^2 hekto h // not supported
#10^1 deka da // not supported
1 // unity
#10^-1 deci d // not supported
#10^-2 centi c // not supported
10^-3 milli m
10^-6 micro u
10^-9 nano n
10^-12 pico p
10^-15 femto f
10^-18 atto a
10^-21 zepto z
10^-24 yocto y

Definition at line 1171 of file StrFunc.cpp.

Module Description

Macros

Functions

Macro Definition Documentation

◆ HASH_STRING_ALGORITHM_DEFAULT

◆ HASH_STRING_ALGORITHM_X65599

◆ HASH_STRING_ALGORITHM_INVALID

◆ DEF_DATETIME_FMT

Function Documentation

◆ SplitUncPath()

◆ SplitNetShareName()

◆ WithoutBackslash()

◆ WithBackslash()

◆ GetRootOf()

◆ StrFmt()

◆ ReplaceStrChar()

◆ MatchPattern()

◆ DeduplicateCharSepText()

◆ PrependString()

◆ AppendString()

◆ GetStringHash()

◆ HexString()

◆ DataSizeStr()

◆ IsoDataSizeStr()

◆ FileAttribStr()

◆ FileTimeStr()

◆ SysTimeStr()

◆ FileTypeStr()

◆ EngFormat()