Multi String and CSV functions
[Utilities]

Defines
#define	KHM_PREFIX   8
#define	KHM_CASE_SENSITIVE   16
#define	KHM_MAXCCH_STRING   16384
#define	KHM_MAXCB_STRING   (KHM_MAXCCH_STRING * sizeof(wchar_t))
Functions
KHMEXP khm_int32 KHMAPI	multi_string_init (wchar_t *ms, khm_size cb_ms)
	Initialize a multi-string.
KHMEXP khm_int32 KHMAPI	multi_string_prepend (wchar_t *ms, khm_size *pcb_ms, const wchar_t *str)
	Prepend a string to a multi string.
KHMEXP khm_int32 KHMAPI	multi_string_append (wchar_t *ms, khm_size *pcb_ms, const wchar_t *str)
	Append a string to a multi-string.
KHMEXP khm_int32 KHMAPI	multi_string_delete (wchar_t *ms, const wchar_t *str, const khm_int32 flags)
	Deletes a string from a multi string.
KHMEXP wchar_t *KHMAPI	multi_string_find (const wchar_t *ms, const wchar_t *str, const khm_int32 flags)
	Search a multi string for a string.
KHMEXP khm_int32 KHMAPI	multi_string_to_csv (wchar_t *csvbuf, khm_size *pcb_csvbuf, const wchar_t *ms)
	Convert a multi string to CSV.
KHMEXP khm_int32 KHMAPI	csv_to_multi_string (wchar_t *ms, khm_size *pcb_ms, const wchar_t *csv)
	Converts a CSV to a multi string.
KHMEXP wchar_t *KHMAPI	multi_string_next (const wchar_t *str)
	Get the next string in a multi string.
KHMEXP khm_int32 KHMAPI	multi_string_length_cb (const wchar_t *str, khm_size max_cb, khm_size *len_cb)
	Get the length of a multi string in bytes.
KHMEXP khm_int32 KHMAPI	multi_string_length_cch (const wchar_t *str, khm_size max_cch, khm_size *len_cch)
	Get the length of a multi string in characters.
KHMEXP khm_size KHMAPI	multi_string_length_n (const wchar_t *str)
	Get the number of strings in a multi string.
KHMEXP khm_int32 KHMAPI	multi_string_copy_cb (wchar_t *s_dest, khm_size max_cb_dest, const wchar_t *src)
	Copy a multi string with byte counts.
KHMEXP khm_int32 KHMAPI	multi_string_copy_cch (wchar_t *s_dest, khm_size max_cch_dest, const wchar_t *src)
	Copy a multi string with character count.

---

Function Documentation

KHMEXP khm_int32 KHMAPI csv_to_multi_string	(	wchar_t *	ms,
		khm_size *	pcb_ms,
		const wchar_t *	csv
	)

Converts a CSV to a multi string.

Undoes what multi_string_to_csv() does.

Parameters:

[out]	ms	The buffer that recieves the multi string. This can be NULL if only the size of the buffer is requried.
[in,out]	pcb_ms	On entry contains the number of bytes ni the buffer poitned to by ms. On exit contains the number of bytes that were copied to ms including terminating NULLs, or if the buffer was too small or ms was NULL, holds the size in bytes of the requied buffer.
[in]	csv	The CSV string.

Return values:

	KHM_ERROR_SUCCESS	The CSV string was successfully converted. The number of bytes written is in pcb_ms.
	KHM_ERROR_TOO_LONG	The provided buffer was too small or ms was NULL. The required size of the buffer in bytes is in pcb_ms.
	KHM_ERROR_INVALID_PARAM	One or more parameters were invalid.

KHMEXP khm_int32 KHMAPI multi_string_append	(	wchar_t *	ms,
		khm_size *	pcb_ms,
		const wchar_t *	str
	)

Append a string to a multi-string.

Appends the string specified by str to the multi string specified by ms. The size of the multi string in characters including terminating NULLs after appending str can not exceed KHM_MAXCCH_STRING.

Parameters:

[in]	ms	The buffer containing the multi string
[in,out]	pcb_ms	Points to a khm_int32 indicating the size of the buffer pointed to by ms. On entry this contains the size (in bytes) of the buffer pointed to by ms. On exit, contains the new size of the multi string in bytes.
[in]	str	The string to append to the multi string. This string cannot be NULL or an empty (zero length) string. The length of str cannot exceed KHM_MAXCCH_STRING in characters including terminating NULL.

Return values:

	KHM_ERROR_SUCCESS	The string was appended to the multi string
	KHM_ERROR_TOO_LONG	The buffer pointed to by ms was insufficient. The required size of the buffer is in pcb_ms
	KHM_ERROR_INVALID_PARAM	One of more of the parameters were invalid.

KHMEXP khm_int32 KHMAPI multi_string_copy_cb	(	wchar_t *	s_dest,
		khm_size	max_cb_dest,
		const wchar_t *	src
	)

Copy a multi string with byte counts.

Copy a multi string from one location to another.

Parameters:

[out]	s_dest	Receives a copy of the multi string
[in]	max_cb_dest	Number of bytes in the buffer pointed to by s_dest.
[in]	src	The source multi string

Return values:

	KHM_ERROR_SUCCESS	The multi string was copied successfully
	KHM_ERROR_INVALID_PARAM	One or more parameters were invalid.
	KHM_ERROR_TOO_LONG	The size of the destination buffer was insufficient.

KHMEXP khm_int32 KHMAPI multi_string_copy_cch	(	wchar_t *	s_dest,
		khm_size	max_cch_dest,
		const wchar_t *	src
	)

Copy a multi string with character count.

Copy a multi string from one location to another.

Parameters:

[out]	s_dest	Receives a copy of the multi string
[in]	max_cb_dest	Number of characters in the buffer pointed to by s_dest.
[in]	src	The source multi string

Return values:

	KHM_ERROR_SUCCESS	The multi string was copied successfully
	KHM_ERROR_INVALID_PARAM	One or more parameters were invalid.
	KHM_ERROR_TOO_LONG	The size of the destination buffer was insufficient.

KHMEXP khm_int32 KHMAPI multi_string_delete	(	wchar_t *	ms,
		const wchar_t *	str,
		const khm_int32	flags
	)

Deletes a string from a multi string.

Deletes the string specified by str from the multi string specified by ms. How the string is matched to the strings in ms is determined by flags. If more than one match is found, then only the first match is deleted.

Parameters:

[in]	ms	The multi string to modify. The length of the multi string in characters cannot exceed KHM_MAXCCH_STRING.
[in]	str	The string to search for
[in]	flags	How str is to be matched to existing strings in ms. This could be a combination of KHM_PREFIX and KHM_CASE_SENSITIVE. If KHM_PREFIX is used, then ms is searched for a string that begins with str. Otherwise, str must match the an entire string in the multi string. If KHM_CASE_SENSITIVE is specified, then a case sensitive match is performed. The defualt is to use a case insensitive search.

Return values:

	KHM_ERROR_SUCCESS	A string was matched and deleted from ms
	KHM_ERROR_NOT_FOUND	No matches were found
	KHM_ERROR_INVALID_PARAM	One or more parameters were incorrect.

Note:

The search for the existing string is done with multi_string_find()

KHMEXP wchar_t* KHMAPI multi_string_find	(	const wchar_t *	ms,
		const wchar_t *	str,
		const khm_int32	flags
	)

Search a multi string for a string.

Searches the string specified by ms for a string that matches str. How the match is performed is determined by flags. Returns a poitner to the start of the matched string in ms. If more than one string in ms matches str, then only the first match is returned.

Parameters:

[in]	ms	The multi string to search in. The length of the multi string cannot exceed KHM_MAXCCH_STRING in characters.
[in]	str	The string to search for
[in]	flags	How str is to be matched to existing strings in ms. This could be a combination of KHM_PREFIX and KHM_CASE_SENSITIVE. If KHM_PREFIX is used, then ms is searched for a string that begins with str. Otherwise, str must match the an entire string in the multi string. If KHM_CASE_SENSITIVE is specified, then a case sensitive match is performed. The defualt is to use a case insensitive search.

Returns:

A pointer to the start of the first matched string or NULL if no matches were found.

KHMEXP khm_int32 KHMAPI multi_string_length_cb	(	const wchar_t *	str,
		khm_size	max_cb,
		khm_size *	len_cb
	)

Get the length of a multi string in bytes.

The returned length includes the trailing double NULL and any other NULL inbetween.

Parameters:

[in]	str	Pointer to a multi string.
[in]	max_cb	Maximum size that the str can be. This can not be larger than KHM_MAXCB_STRING.
[out]	len_cb	The length of the string in bytes if the call is successful.

Return values:

	KHM_ERROR_SUCCESS	The length of the string is in len_cb
	KHM_ERROR_INVALID_PARAM	One or more parameters were invalid
	KHM_ERROR_TOO_LONG	The multi string is longer than max_cb bytes.

KHMEXP khm_int32 KHMAPI multi_string_length_cch	(	const wchar_t *	str,
		khm_size	max_cch,
		khm_size *	len_cch
	)

Get the length of a multi string in characters.

The returned length includes the trailing double NULL and any other NULL inbetween.

Parameters:

[in]	str	Pointer to a multi string.
[in]	max_cch	Maximum size that the str can be. This can not be larger than KHM_MAXCCH_STRING.
[out]	len_cch	The length of the string in characters if the call is successful.

Return values:

	KHM_ERROR_SUCCESS	The length of the string is in len_cch
	KHM_ERROR_INVALID_PARAM	One or more parameters were invalid
	KHM_ERROR_TOO_LONG	The multi string is longer than max_cch characters.

KHMEXP wchar_t* KHMAPI multi_string_next

(

const wchar_t *

str

)

Get the next string in a multi string.

When str is pointing to a string that is in a multi string, this function returns a pointer to the next string in the multi string.

Typically, one would start by having str point to the start of the multi string (which is the first string in the multi string), and then call this function repeatedly, until it returns NULL, at which point the end of the multi string has been reached.

Parameters:

[in]

str

Pointer to a string in a multi string. Each string in a multi string cannot exceed KHM_MAXCCH_STRING in charaters including the terminating NULL.

Returns:

A pointer to the start of the next string in the multi string or NULL if there is no more strings.

KHMEXP khm_int32 KHMAPI multi_string_prepend	(	wchar_t *	ms,
		khm_size *	pcb_ms,
		const wchar_t *	str
	)

Prepend a string to a multi string.

Adds the string str to the beginning of multi-string ms.

Parameters:

[in,out]	ms	The multi-string to be modified.
[in,out]	pcb_ms	A pointer to the size of the multistring. On entry this specifies the size of the buffer pointed to by ms. If the call is successful, on exit this will receive the new size of the multi string in bytes. If the buffer is insufficient, the function will return KHM_ERROR_TOO_LONG and set this to the required size of the buffer in bytes.
[in]	str	The string to prepend to ms. This cannot be longer than KHM_MAXCCH_STRING in characters including the terminating NULL.

KHMEXP khm_int32 KHMAPI multi_string_to_csv	(	wchar_t *	csvbuf,
		khm_size *	pcb_csvbuf,
		const wchar_t *	ms
	)

Convert a multi string to CSV.

Converts a multi string to a comma separated value string based on the following rules.

• Each string in the multi string is treated an individual field

• A field is quoted if it has double quotes or commas

• Double quotes within quoted fields are escaped by two consecutive double quotes.

For example:

    multi_string = L"foo\0bar\0baz,quux\0ab\"cd\0";
    csv_string = L"foo,bar,\"baz,quux\",\"ab\"\"cd\"";

If multi_string_to_csv() is called on multi_string above, you would obtain csv_string.

Parameters:

[out]	csvbuf	The buffer to place the CSV string in. Can be NULL if only teh size of the needed buffer is required.
[in,out]	pcb_csvbuf	On entry, points to a khm_int32 that holds the size of the buffer pointed to by csvbuf. On exit, gets the number of bytes writted to csvbuf or the required size of csvbuf if the buffer is too small or csvbuf is NULL.
[in]	ms	The mutli string to convert to a CSV.

Return values:

	KHM_ERROR_SUCCESS	The multi string was successfully converted to a CSV string. The number of bytes written is in pcb_csvbuf. The count includes the terminating NULL.
	KHM_ERROR_TOO_LONG	The buffer was too small or csvbuf was NULL. The required number of bytes in the buffer is in pcb_csvbuf.
	KHM_ERROR_INVALID_PARAM	One or more parameters were ivnalid.

See also:

csv_to_multi_string()

---