Module string Methods

AcquireString() allocates memory for a string and copies the source string to that memory location (and returns it).

The format of the AcquireString method is:

  char *AcquireString(const char *source)

A description of each parameter follows:

allocated_string

Method AcquireString returns a copy of the source string.

source

A character string.

AcquireStringInfo() allocates the StringInfo structure.

The format of the AcquireStringInfo method is:

  StringInfo *AcquireStringInfo(const size_t length)

A description of each parameter follows:

length

The string length.

CloneString() allocates memory for the destination string and copies the source string to that memory location.

The format of the CloneString method is:

  char *CloneString(char **destination,const char *source)

A description of each parameter follows:

destination

A pointer to a character string.

source

A character string.

CloneStringInfo() clones a copy of the StringInfo structure.

The format of the CloneStringInfo method is:

  StringInfo *CloneStringInfo(const StringInfo *string_info)

A description of each parameter follows:

string_info

The string info.

CompareStringInfo() compares the two datums target and source. It returns an integer less than, equal to, or greater than zero if target is found, respectively, to be less than, to match, or be greater than source.

The format of the CompareStringInfo method is:

  int CompareStringInfo(const StringInfo *target,const StringInfo *source)

A description of each parameter follows:

target

The target string.

source

The source string.

ConcatenateString() appends a copy of string source, including the terminating null character, to the end of string destination.

The format of the ConcatenateString method is:

  WizardBooleanType ConcatenateString(char **destination,
    const char *source)

A description of each parameter follows:

destination

A pointer to a character string.

source

A character string.

ConcatenateWizardString() concatenates the source string to the destination string. The destination buffer is always null-terminated even if the string must be truncated.

The format of the ConcatenateWizardString method is:

  size_t ConcatenateWizardString(char *destination,const char *source,
    const size_t length)

A description of each parameter follows:

destination

The destination string.

source

The source string.

length

The length of the destination string.

ConfigureFileToStringInfo() returns the contents of a configure file as a string.

The format of the ConfigureFileToStringInfo method is:

  StringInfo *ConfigureFileToStringInfo(const char *filename)
    ExceptionInfo *exception)

A description of each parameter follows:

filename

The filename.

ConstantString() allocates memory for a string and copies the source string to that memory location (and returns it). Use it for strings that you do do not expect to change over its lifetime.

The format of the ConstantString method is:

  char *ConstantString(const char *source)

A description of each parameter follows:

source

A character string.

ConcatenateStringInfo() concatenates the source string to the destination string.

The format of the ConcatentateStringInfo method is:

  void ConcatentateStringInfo(StringInfo *string_info,
    const StringInfo *source)

A description of each parameter follows:

string_info

The string info.

source

The source string.

CopyWizardString() copies the source string to the destination string. The destination buffer is always null-terminated even if the string must be truncated. The return value is the minimum of the ource string length or the length parameter.

The format of the CopyWizardString method is:

  size_t CopyWizardString(const char *destination,char *source,
    const size_t length)

A description of each parameter follows:

destination

The destination string.

source

The source string.

length

The length of the destination string.

DestroyString() destorys memory associated with a string.

The format of the DestroyString method is:

  char *DestroyString(char *string)

A description of each parameter follows:

string

The string.

DestroyStringInfo() zeros memory associated with the StringInfo structure.

The format of the DestroyStringInfo method is:

  StringInfo *DestroyStringInfo(StringInfo *string_info)

A description of each parameter follows:

string_info

The string info.

DestroyStringList() zeros memory associated with a string list.

The format of the DestroyStringList method is:

  char **DestroyStringList(char **list)

A description of each parameter follows:

list

The string list.

FileToString() returns the contents of a file as a string.

The format of the FileToString method is:

  char *FileToString(const char *filename,const size_t extent,
    ExceptionInfo *exception)

A description of each parameter follows:

filename

The filename.

extent

Maximum length of the string.

exception

Return any errors or warnings in this structure.

FileToStringInfo() returns the contents of a file as a string.

The format of the FileToStringInfo method is:

  StringInfo *FileToStringInfo(const char *filename,const size_t extent,
    ExceptionInfo *exception)

A description of each parameter follows:

filename

The filename.

extent

Maximum length of the string.

exception

Return any errors or warnings in this structure.

FormatWizardSize() converts a size to a human readable format, for example, 14k, 234m, 2.7g, or 3.0t. Scaling is done by repetitively dividing by 1000.

The format of the FormatWizardSize method is:

  ssize_t FormatWizardSize(const WizardSizeType size,char *format)

A description of each parameter follows:

size

convert this size to a human readable format.

bi

use power of two rather than power of ten.

format

human readable format.

FormatWizardString() prints formatted output of a variable argument list.

The format of the FormatWizardString method is:

  ssize_t FormatWizardString(char *string,const size_t length,
    const char *format,...)

A description of each parameter follows.

string

FormatWizardString() returns the formatted string in this character buffer.

length

The maximum length of the string.

format

A string describing the format to use to write the remaining arguments.

FormatWizardTime() returns the specified time in the Internet date/time format and the length of the timestamp.

The format of the FormatWizardTime method is:

  ssize_t FormatWizardTime(const time_t time,const size_t length,
    char *timestamp)

A description of each parameter follows.

time

the time since the Epoch (00:00:00 UTC, January 1, 1970), measured in seconds.

length

The maximum length of the string.

timestamp

Return the Internet date/time here.

GetEnvironmentValue() returns the environment string that matches the specified name.

The format of the GetEnvironmentValue method is:

  char *GetEnvironmentValue(const char *name)

A description of each parameter follows:

name

the environment name.

GetStringInfoCRC() returns the CRC-64 of a string.

The format of the GetStringInfo method is:

  WizardSizeType GetStringInfo(const StringInfo *string_info)

A description of each parameter follows:

string_info

The string info.

GetStringInfoDatum() returns the datum associated with the string.

The format of the GetStringInfoDatum method is:

  unsigned char *GetStringInfoDatum(const StringInfo *string_info)

A description of each parameter follows:

string_info

the string info.

GetStringInfoLength() returns the string length.

The format of the GetStringInfoLength method is:

  size_t GetStringInfoLength(const StringInfo *string_info)

A description of each parameter follows:

string_info

the string info.

GetStringInfoPath() returns the path associated with the string.

The format of the GetStringInfoPath method is:

  const char *GetStringInfoPath(const StringInfo *string_info)

A description of each parameter follows:

string_info

the string info.

HexStringToStringInfo() returns the contents of a file as a string.

The format of the HexStringToStringInfo method is:

  StringInfo *HexStringToStringInfo(const char *string)

A description of each parameter follows:

string

The string.

LocaleCompare() performs a case-insensitive comparison of two strings byte-by-byte, according to the ordering of the current locale encoding. LocaleCompare returns an integer greater than, equal to, or less than 0, if the string pointed to by p is greater than, equal to, or less than the string pointed to by q respectively. The sign of a non-zero return value is determined by the sign of the difference between the values of the first pair of bytes that differ in the strings being compared.

The format of the LocaleCompare method is:

  int LocaleCompare(const char *p,const char *q)

A description of each parameter follows:

p

A pointer to a character string.

q

A pointer to a character string to compare to p.

LocaleLower() transforms all of the characters in the supplied null-terminated string, changing all uppercase letters to lowercase.

The format of the LocaleLower method is:

  void LocaleLower(char *string)

A description of each parameter follows:

string

A pointer to the string to convert to lower-case Locale.

LocaleNCompare() performs a case-insensitive comparison of two strings byte-by-byte, according to the ordering of the current locale encoding. LocaleNCompare returns an integer greater than, equal to, or less than 0, if the string pointed to by p is greater than, equal to, or less than the string pointed to by q respectively. The sign of a non-zero return value is determined by the sign of the difference between the values of the first pair of bytes that differ in the strings being compared. The LocaleNCompare method makes the same comparison as LocaleCompare but looks at a maximum of n bytes. Bytes following a null byte are not compared.

The format of the LocaleNCompare method is:

  int LocaleNCompare(const char *p,const char *q,const size_t n)

A description of each parameter follows:

p

A pointer to a character string.

q

A pointer to a character string to compare to p.

length

The number of characters to compare in strings p and q.

PrintWizardString() prints the string to the specified file.

The format of the PrintWizardString method is:

  ssize_t PrintWizardString(FILE *,const char *format,...)

A description of each parameter follows:

file

print to this file.

format

A string describing the format to use to write the remaining arguments.

PrintStringInfo() prints the string.

The format of the PrintStringInfo method is:

  void PrintStringInfo(FILE *file,const char *id,
    const StringInfo *string_info)

A description of each parameter follows:

id

The string id.

string_info

The string info.

ResetStringInfo() reset the string to all null bytes.

The format of the ResetStringInfo method is:

  void ResetStringInfo(StringInfo *string_info)

A description of each parameter follows:

string_info

The string info.

SetStringInfo() copies the source string to the destination string.

The format of the SetStringInfo method is:

  void SetStringInfo(StringInfo *string_info,const StringInfo *source)

A description of each parameter follows:

string_info

The string info.

source

The source string.

SetStringInfoDatum() copies bytes from the source string for the length of the destination string.

The format of the SetStringInfoDatum method is:

  void SetStringInfoDatum(StringInfo *string_info,
    const unsigned char *source)

A description of each parameter follows:

string_info

The string info.

source

The source string.

SetStringInfoLength() set the string length to the specified value.

The format of the SetStringInfoLength method is:

  void SetStringInfoLength(StringInfo *string_info,const size_t length)

A description of each parameter follows:

string_info

The string info.

length

The string length.

SetStringInfoPath() sets the path associated with the string.

The format of the SetStringInfoPath method is:

  void SetStringInfoPath(StringInfo *string_info,const char *path)

A description of each parameter follows:

string_info

The string info.

path

The path.

SplitStringInfo() splits a string into two and returns it.

The format of the SplitStringInfo method is:

  StringInfo *SplitStringInfo(StringInfo *string_info,const size_t offset)

A description of each parameter follows:

string_info

The string info.

StringInfoToHexString() converts a string info string to a C string.

The format of the StringInfoToHexString method is:

  char *StringInfoToHexString(const StringInfo *string_info)

A description of each parameter follows:

string_info

The string.

StringInfoToString() converts a string info string to a C string.

The format of the StringInfoToString method is:

  char *StringInfoToString(const StringInfo *string_info)

A description of each parameter follows:

string_info

The string.

StringToArgv() converts a text string into command line arguments.

The format of the StringToArgv method is:

  char **StringToArgv(const char *text,int *argc)

A description of each parameter follows:

argv

Method StringToArgv returns the string list unless an error occurs, otherwise NULL.

text

Specifies the string to segment into a list.

argc

This integer pointer returns the number of arguments in the list.

StringToStringInfo() returns the contents of a file as a string.

The format of the StringToStringInfo method is:

  StringInfo *StringToStringInfo(const char *string)

A description of each parameter follows:

string

The string.

StripString() strips any whitespace or quotes from the beginning and end of a string of characters.

The format of the StripString method is:

  void StripString(char *message)

A description of each parameter follows:

message

Specifies an array of characters.

SubstituteString() performs string substitution on a string, replacing the string with the substituted version. Buffer must be allocated from the heap. If the string is matched and status, WizardTrue is returned otherwise WizardFalse.

The format of the SubstituteString method is:

  WizardBooleanType SubstituteString(char **string,const char *search,
    const char *replace)

A description of each parameter follows:

string

the string to perform replacements on; replaced with new allocation if a replacement is made.

search

search for this string.

replace

replace any matches with this string.