# Ustdlib_api

## Functions
int | uvsnprintf (char *pcBuf, unsigned long ulSize, const char *pcString, va_list vaArgP)
int | usprintf (char *pcBuf, const char *pcString,...)
int | usnprintf (char *pcBuf, unsigned long ulSize, const char *pcString,...)
void | ulocaltime (unsigned long ulTime, tTime *psTime)
unsigned long | ustrtoul (const char *pcStr, const char **ppcStrRet, int iBase)
char * | ustrstr (const char *pcHaystack, const char *pcNeedle)
int | ustrnicmp (const char *pcStr1, const char *pcStr2, int iCount)

## Function Documentation

void ulocaltime | ( | unsigned long | ulTime,
|  | tTime * | psTime |
| ) |  |  |

Converts from seconds to calendar date and time.

Parameters:

  | ulTime | is the number of seconds.
  | psTime | is a pointer to the time structure that is filled in with the broken down date and time.

This function converts a number of seconds since midnight GMT on January 1, 1970 (traditional Unix epoch) into the equivalent month, day, year, hours, minutes, and seconds representation.

Returns:
  None.

int usnprintf | ( | char * | pcBuf,
|  | unsigned long | ulSize,
|  | const char * | pcString,
|  |  | ... |
| ) |  |  |

A simple snprintf function supporting %c, %d, %p, %s, %u, %x, and %X.

Parameters:

  | pcBuf | is the buffer where the converted string is stored.
  | ulSize | is the size of the buffer.
  | pcString | is the format string.
  | ... | are the optional arguments, which depend on the contents of the format string.

This function is very similar to the C library `sprintf()` function. Only the following formatting characters are supported:

- %c to print a character
- %d to print a decimal value
- %s to print a string
- %u to print an unsigned decimal value
- %x to print a hexadecimal value using lower case letters
- %X to print a hexadecimal value using lower case letters (not upper case letters as would typically be used)
- %p to print a pointer as a hexadecimal value
- %% to print out a % character

For %d, %p, %s, %u, %x, and %X, an optional number may reside between the % and the format character, which specifies the minimum number of characters to use for that value; if preceded by a 0 then the extra characters will be filled with zeros instead of spaces. For example, ``%8d'' will use eight characters to print the decimal value with spaces added to reach eight; ``%08d'' will use eight characters as well but will add zeros instead of spaces.

The type of the arguments after pcString must match the requirements of the format string. For example, if an integer was passed where a string was expected, an error of some kind will most likely occur.

The function will copy at most ulSize - 1 characters into the buffer pcBuf. One space is reserved in the buffer for the null termination character.

The function will return the number of characters that would be converted as if there were no limit on the buffer size. Therefore it is possible for the function to return a count that is greater than the specified buffer size. If this happens, it means that the output was truncated.

Returns:
  Returns the number of characters that were to be stored, not including the NULL termination character, regardless of space in the buffer.

int usprintf | ( | char * | pcBuf,
|  | const char * | pcString,
|  |  | ... |
| ) |  |  |

A simple sprintf function supporting %c, %d, %p, %s, %u, %x, and %X.

Parameters:

  | pcBuf | is the buffer where the converted string is stored.
  | pcString | is the format string.
  | ... | are the optional arguments, which depend on the contents of the format string.

This function is very similar to the C library `sprintf()` function. Only the following formatting characters are supported:

- %c to print a character
- %d to print a decimal value
- %s to print a string
- %u to print an unsigned decimal value
- %x to print a hexadecimal value using lower case letters
- %X to print a hexadecimal value using lower case letters (not upper case letters as would typically be used)
- %p to print a pointer as a hexadecimal value
- %% to print out a % character

For %d, %p, %s, %u, %x, and %X, an optional number may reside between the % and the format character, which specifies the minimum number of characters to use for that value; if preceded by a 0 then the extra characters will be filled with zeros instead of spaces. For example, ``%8d'' will use eight characters to print the decimal value with spaces added to reach eight; ``%08d'' will use eight characters as well but will add zeros instead of spaces.

The type of the arguments after pcString must match the requirements of the format string. For example, if an integer was passed where a string was expected, an error of some kind will most likely occur.

The caller must ensure that the buffer pcBuf is large enough to hold the entire converted string, including the null termination character.

Returns:
  Returns the count of characters that were written to the output buffer, not including the NULL termination character.

int ustrnicmp | ( | const char * | pcStr1,
|  | const char * | pcStr2,
|  | int | iCount |
| ) |  |  |

Compares two strings without regard to case.

Parameters:

  | pcStr1 | points to the first string to be compared.
  | pcStr2 | points to the second string to be compared.
  | iCount | is the maximum number of characters to compare.

This function is very similar to the C library `strnicmp()` function. It compares at most iCount characters of two strings without regard to case. The comparison ends if a terminating NULL character is found in either string before iCount characters are compared. In this case, the shorter string is deemed the lesser.

Returns:
  Returns 0 if the two strings are equal, -1 if pcStr1 is less than pcStr2 and 1 if pcStr1 is greater than pcStr2.

char* ustrstr | ( | const char * | pcHaystack,
|  | const char * | pcNeedle |
| ) |  |  |

Finds a substring within a string.

Parameters:

  | pcHaystack | is a pointer to the string that will be searched.
  | pcNeedle | is a pointer to the substring that is to be found within pcHaystack.

This function is very similar to the C library `strstr()` function. It scans a string for the first instance of a given substring and returns a pointer to that substring. If the substring cannot be found, a NULL pointer is returned.

Returns:
  Returns a pointer to the first occurrence of pcNeedle within pcHaystack or NULL if no match is found.

unsigned long ustrtoul | ( | const char * | pcStr,
|  | const char ** | ppcStrRet,
|  | int | iBase |
| ) |  |  |

Converts a string into its numeric equivalent.

Parameters:

  | pcStr | is a pointer to the string containing the integer.
  | ppcStrRet | is a pointer that will be set to the first character past the integer in the string.
  | iBase | is the radix to use for the conversion; can be zero to auto-select the radix or between 2 and 16 to explicitly specify the radix.

This function is very similar to the C library `strtoul()` function. It scans a string for the first token (that is, non-white space) and converts the value at that location in the string into an integer value.

Returns:
  Returns the result of the conversion.

int uvsnprintf | ( | char * | pcBuf,
|  | unsigned long | ulSize,
|  | const char * | pcString,
|  | va_list | vaArgP |
| ) |  |  |

A simple vsnprintf function supporting %c, %d, %p, %s, %u, %x, and %X.

Parameters:

  | pcBuf | points to the buffer where the converted string is stored.
  | ulSize | is the size of the buffer.
  | pcString | is the format string.
  | vaArgP | is the list of optional arguments, which depend on the contents of the format string.

This function is very similar to the C library `vsnprintf()` function. Only the following formatting characters are supported:

- %c to print a character
- %d to print a decimal value
- %s to print a string
- %u to print an unsigned decimal value
- %x to print a hexadecimal value using lower case letters
- %X to print a hexadecimal value using lower case letters (not upper case letters as would typically be used)
- %p to print a pointer as a hexadecimal value
- %% to print out a % character

For %d, %p, %s, %u, %x, and %X, an optional number may reside between the % and the format character, which specifies the minimum number of characters to use for that value; if preceded by a 0 then the extra characters will be filled with zeros instead of spaces. For example, ``%8d'' will use eight characters to print the decimal value with spaces added to reach eight; ``%08d'' will use eight characters as well but will add zeroes instead of spaces.

The type of the arguments after pcString must match the requirements of the format string. For example, if an integer was passed where a string was expected, an error of some kind will most likely occur.

The ulSize parameter limits the number of characters that will be stored in the buffer pointed to by pcBuf to prevent the possibility of a buffer overflow. The buffer size should be large enough to hold the expected converted output string, including the null termination character.

The function will return the number of characters that would be converted as if there were no limit on the buffer size. Therefore it is possible for the function to return a count that is greater than the specified buffer size. If this happens, it means that the output was truncated.

Returns:
  Returns the number of characters that were to be stored, not including the NULL termination character, regardless of space in the buffer.

All Files Functions Variables Defines