zpathnameClean

Description: Copies a pathname removing invalid characters.

Declaration:

int zpathnameClean(char *cleanedPathname, size_t sizeofCleanedPathname,
const char *pathname);

Parameters:

char *cleanedPathname

The char array to copy into (the resulting pathname, with invalid characters removed).

size_t sizeofCleanedPathname

The size of char array cleanedPathname . A pathname can be up to 392 characters long, so this should be 394 (to hold last slash and terminating null).

const char * pathname

The pathname to copy from.

Returns:

int length

The length of the resulting pathname.

Remarks:

Invalid characters include escape codes and DEL (<32, >126).
The pathname is limited to seven slashes "/".

zpathnameCompare

Description: Compare two pathnames, case insensitive.

Declaration:

int zpathnameCompare(const char *pathname1, const char *pathname2,
size_t pathnameLength);

Parameters:

const char *pathname1

The first pathname to compare.

const char *pathname2

The second pathname to compare with.

int pathnameLength

The length of each pathname (Note: both pathnames have to be the same length, so check that first.

Returns:

0 (zero) not the same
1 (One) the same

Remarks:

Case insensitive, may be either upper or lower, results will be the same

zpathnameCompareCollection

Description: Compare two pathnames, except for the collection part. Must be collection pathnames.

Declaration:

int zpathnameCompareCollection (const char *pathname1, const char *pathname2,
size_t pathnameLength);

Parameters:

const char *pathname1

The first pathname to compare.

const char *pathname2

The second pathname to compare with.

int pathnameLength

The length of each pathname (Note: both pathnames have to be the same length, so check that first.

Returns:

0 (zero) not the same
1 (One) the same, except for the collection piece.

Remarks:

Case insensitive, may be either upper or lower, results will be the same

zpathnameForm

Description: Builds a pathname from 6 pathname parts.

Declaration:

int zpathnameForm(const char *aPart, const char *bPart, const char *cPart, const char *dPart, const char *ePart, const char *fPart, char *pathname, size_t sizeofPathname);

Parameters:

const char *aPart

The "A" (first) part of the pathname. This should not contain slashes (/).

const char *bPart

The "B" (second) part of the pathname.

const char *cPart

The "C" (third) part of the pathname.

const char *dPart

The "D" (fourth) part of the pathname.

const char *ePart

The "E" (fifth) part of the pathname.

const char *fPart

The "F" (sixth) part of the pathname.

char *pathname (output)

A char array to contain the resulting pathname. A pathname can be up to 392 characters long, so this should be sized to 394 (to hold last slash and terminating null).

size_t sizeofPathname

The size of pathname char array.

Returns:

int length

The length of the resulting pathname.

zpathnameGetPart

Description: Gets a part from a pathname.

Declaration:

int zpathnameGetPart (const char *pathname, int partPosition, char *part,
int sizeofPart);

Parameters:

const char *pathname

The pathname to get the part from.

int partPosition

The part number to get, where A part = 1, B part = 2, etc.

char *part (output)

A string to hold the part that is returned. This should be dimensioned to 65 chars.

int sizeofPart

The size of part (should be 65).

Returns

int length

The length of part
STATUS_NOT_OKAY if an error (invalid part number or pathname)

zpathnamePartLengths

Description: Determines the length of each part from a pathname

Declaration:

int zpathnamePartLengths (const char *pathname, size_t pathnameLen, int lengths[], int dimOfLengths);

Parameters:

const char *pathname

The pathname to get the part lengths from.

size_t pathnameLen

The number of characters in the pathname (excluding any terminating \0).

int lengths[6]

An int array dimensioned to 6 to hold the length of each part.

int dimOfLengths

The dimension of lengths. Should be 6.

Returns:

int count

The number of parts (should be 6)
STATUS_NOT_OKAY if an error

Remarks:

Use zpathnamePartPositions() to determine the pathname part locations.

zpathnamePartPositions

Description: Determines the starting location of each part of a pathname (first char after slash)

Declaration:

int zpathnamePartPositions (const char *pathname, size_t pathnameLen, int positions[7], int dimOfPositions);

Parameters:

const char *pathname

The pathname to get the part positions from.

size_t pathnameLen

The number of characters in the pathname (excluding any terminating \0).

int positions[7]

An int array dimensioned to 7 to hold the starting position of each part. This should be dimensioned to 7 to get the end of the F part.

int dimOfPositions

The dimension of positions. Should be 7.

Returns:

int count
The number of positions (should be 7)
STATUS_NOT_OKAY if an error.

Remarks:

The 7th position contains the character location one char after the last slash (usually '\0' position)

For the B part: Start of B part = positions[1];
End of B part = positions[2] - 2;
Length of B part = positions[2] - positions[1] - 1;
B part = pathname(positions[1], positions[2] - 2)

For the F part: Start of F part = positions[6];
End of F part = positions[7] - 2;
Length of F part = positions[7] - positions[6] - 1;
F part = pathname(positions[7], positions[7] - 2)

zpathnameSetPart

Description: Set (Replaces) a part of a pathname

Declaration:

int zpathnameSetPart (char *pathname, size_t sizeofPathname, const char *part,
int partPosition);

Parameters:

const char *pathname

The pathname to set the part into. This must be a valid pathname, as this function only replaces a part.

size_t sizeofPathname

The size (dimension) of the pathname.

const char *part

The part that will be set in pathname.

int partPosition

The part number to set, where A part = 1, B part = 2, etc.

Returns:

STATUS_OKAY
STATUS_NOT_OKAY for error (sizeofPathname too small or invalid position)

zpathnameAddPart

Description: Trims and appends a part for building a pathname. Adds trailing slash. Used by zpathnameForm() to build a full pathname from parts.

Declaration:

int zpathnameAddPart(const char *part, int count, char *pathname,
size_t sizeofPathname);

Parameters:

const char *part

The pathname part to append (input). This should not contain slashes (/).

int count

The current length of the pathname being built (input).

char *pathname

The pathname being built (input-output).

size_t sizeofPathname

The size of pathname (input).

Returns:

int count

The length of the resulting (partial) pathname

getFileFromPath

Description: Parses a file name and returns the name without the path (but includes extension).

Declaration:

char *getFileFromPath (char *filename, size_t sizeOfFilename, const char *fullpath);

Parameters:

char *filename

The file name only (with extension). This should be declared as char filename[_MAX_FNAME];

size_t sizeOfFilename

The size of the char array filename. (Should be _MAX_FNAME)

const char *fullpath

The path/file name to parse.

Returns:

char *filename or
NULL if invalid file name.

zfindString

Description: Finds the position of one string within another, case insensitive.

Declaration:

int zfindString(const char *fullString, int fullStringLength, const char *stringToFind, int stringToFindLength);

Parameters:

const char *fullString
The string to search.

int fullStringLength
The length of fullString.

const char *stringToFind
The string to look for in fullString.

int stringToFindLength
The length of stringToFind.

Returns:

int position
The position in fullString where stringToFind starts
0 for fullStringLength
-1 if fullString does not contain stringToFind.

Remarks:

Case insensitive, may be either upper or lower, results will be the same

lowerCase

Description: A utility function that converts a string to lower case.

Declaration:

void lowerCase(char *string)

Parameters:

char *string
string to convert to lower case

Remarks:

Must be null terminated.

upperCase

Description: A utility function that converts a string to upper case.

Declaration:

void upperCase(char *string)

Parameters:

char *string
string to convert to upper case

Remarks:

Must be null terminated.

mallocAndCopy

Description: Allocates space and then copies the provided string into it, removing any trailing blanks.

Declaration:

char *mallocAndCopy(const char *copyFrom);

Parameters:

const char* copyFrom
Character string to copy from.

Returns:

Copy of the character string with trailing blanks removed. null if malloc fails.

Remarks:

Strings are null terminated.

mallocAndCopyPath

Description: Same as mallocAndCopy, but ensures that there are (only) seven slashes

Declaration:

char *mallocAndCopyPath(const char * copyFromPathname);

Parameters:

const char* copyFromPathname
Character string to copy from.

Returns:

Copy of the character string with trailing blanks removed. null if malloc fails.

Remarks:

Strings are null terminated.

mallocAndCopyTrim

Description: Same as mallocAndCopy, but removes any leading or trailing blanks

Declaration:

char *mallocAndCopyTrim(const char *copyFromString);

Parameters:

const char* copyFromString
Character string to copy from.

Returns:

Copy of the character string with leading and trailing blanks removed. null if malloc fails

stringCat

Description: Replaces strncat_s for compatibility between various OS.

Declaration:

int stringCat (char destination, size_t sizeOfDestination, const char source,
size_t lenSource)

Parameters:

char *destination
Character string to copy into

size_t sizeOfDestination

The size of the destination string. This should be at least one more than the number of characters that will be copied into destination to hold null pointer.

const char* source
Character string to copy from.

size_t lenSource
Number of characters to copy, or if source is null terminated, can be _TRUNCATE or sizeof.

Returns:

Pointer to the resulting string dest.

stringCopy

Description: Replaces strncpy_s to be cross platform usable and more controllable.

Declaration:

int stringCopy (char destination, size_t sizeOfDestination, const char source,
size_t lenSource)

Parameters:

char *destination
Character string to copy into.

size_t sizeOfDestination

The size of the destination string. This should be at least one more than the number of characters that will be copied into destination to hold null pointer.

const char* source
Character string to copy from.

size_t lenSource
Number of characters to copy, or if source is null terminated, can be _TRUNCATE or sizeof.

Returns:

Length of the destination string.

Remarks:

destination will always be null terminated.
If destination is too small to hold the number of characters to copy, the number that will be copied will be (sizeOfDestination-1) and the last character in destination will be '\0'.

An example of an issue with strncpy_s is that when 10 characters were copied from a 20 character array and the destination size was only 5, strncpy_s barfed and halted the program. stringCopy will only copy 4 + null. No barfing.

stringFill

Description: A utility function to fill a character string with a single character.

Declaration:

void stringFill (char *string, char cval, size_t len);

Parameters:

char *string
The character string to fill.

char cval
A character to fill the string with.

size_t len
The number of characters to fill.

stringLastNonBlank

Description: Trims ending blanks in a string.

Declaration:

int stringLastNonBlank (char *string, size_t len);

Parameters:

char *string
The character string to trim.

size_t stringSize
The size of the string.

Returns:

The length of the string

Remarks:

This function is often used for converting a Fortran string to C, as Fortran strings are blank padded and have no terminating null character.

trimLength, trimLengthLen

Description: Returns the length of the last non-blank character of a string

Declaration:

size_t trimLength(const char *string);
size_t trimLengthLen(const char *string, size_t len);

Parameters:

const char *string
The character string to find the last non-blank character in.

size_t len

The position of the string to start scanning backwards from. This is useful is the string is not necessarily null terminated or you know where the last ending blank is.

Returns:

size_t len
The length to the last non-blank character.

Notes:

Returns the number of characters, not the position or index. (pos = len - 1)

Examples:

len = trimLength(" AB C DE "); // len = 8, length to of "E"
len = trimLengthLen(" AB C DE ", 9); // len = 8
len = trimLengthLen(" AB C DE ", 5); // len = 5, length to of "C"

trimPositions

Description: Determines the first and last non-blank character positions of a string

Declaration:

int trimPositions(const char *string, int *start, int *end);

Parameters:

const char *string

The character string to find the first and last non-blank character in (exclusive of '\0')

int *start (output)

Returns the position of the first non-blank character. For example, "ABC" returns 0, " ABC" returns 1.

int *end (output)

Returns the position of the last non-blank character (excluding null). For example, "ABC " returns 2, " ABC " returns 3.

Returns:

The length of the string without leading or trailing blanks.
Returns 0 if all blanks.

Example:

stringCopy(mystr, sizeof(mystr), " My String ", _TRUNCATE);
i = trimPositions(mystr, &start, &end);
// i == 9, start == 2, y == 10
if (i) {
end++;
mystr[end] = '\0';
str = mallocAndCopy(&mystr[start]);
}
else {
str = mallocAndCopy("\0");
}
// str = "My String"

reverseNonNumeric

Description: Finds the last non-numeric character of a string.

Declaration:

char *reverseNonNumeric(const char *string);

Parameters:

const char *string
A string that contains may contain a mix of alpha and numeric characters.

Returns:

char*
The last non-numeric character
Null, if all numeric

Examples:

23Mar1994" returns "r"
"1234" returns null

Remarks:

An ASCII dependent function.

longWithCommas

Description: A small utility function for converting a long to a string with commas (e.g. "12,345,678"). Usually used for printing.

Declaration:

int longWithCommas(char *str, size_t strSize, long long number);

Parameters:

char *str
A character string to contain the number with comma.

size_t strSize
The size of str

long long number
The number to convert to a string with commas

Returns:

The length of the string, or -1 if str is not large enough.

zsetCollectionSequence

Description: Creates a collection pathname using the provided sequence number.

Declaration:

char* zsetCollectionSequence(char* pathname, int sequenceNumber);

Parameters:

char *pathname
The pathname to make a collections path from.

int sequenceNumber
The sequence number to set

Returns:

char *collectionPathname

A malloc of the input pathname with the F part set to the collection sequence number. BE SURE TO FREE this pathname when done. null if the input pathname is not a valid pathname

Note:

Collections are identified by an F part of /C:000000|REST OF FPART/ Where 00000 is generally a sequence number.

Example:

("/YUBA/SMARTSVILLE/FLOW/01JAN1997/1HOUR/OPERATION A/", 42);
returns
"/YUBA/SMARTSVILLE/FLOW/01JAN1997/1HOUR/C:000042|OPERATION A/"