'Multi-Byte' Character Set utility functions More...

Functions
char *	WBInsertMBChars (char pString, int iCol, const char pszMBString, int cbString, int fTab, int fOverwrite, int piNewCol, char *ppInserted)
	Insert multi-byte characters into a WBAlloc'd string, at a specified column. More...

char *	WBSplitMBLine (char *pString, int iCol)
	Split a multi-byte characters into a WBAlloc'd string, at a specified column, terminating the original string at that column with a zero byte. More...

char *	WBJoinMBLine (char pString, int iCol, const char pJoin)
	Split a multi-byte characters into a WBAlloc'd string, at a specified column, terminating the original string at that column with a zero byte. More...

int	WBDelMBChars (char pString, int iCol, int nDel, int piNewCol, char **ppDeleted)
	Delete a specified number of multi-byte characters from a string 'in place', starting at a specified column. More...

int	WBGetMBLength (const char *pString)
	Obtain the length of a multi-byte character string in 'characters' (not bytes) More...

char *	WBGetMBCharPtr (char pString, int iCol, int pcbLen)
	Obtain the pointer to a specific multi-byte character within a multi-byte character string, by specifying it's column. More...

int	WBGetMBColIndex (const char pString, const char pChar)
	Obtain the column index from a pointer within a multi-byte character string. More...

Detailed Description

'Multi-Byte' Character Set utility functions

Utility functions for working with Multi-Byte character sets (MBCS). These are primarily intended for use with 'Text Objects'.

Function Documentation

◆ WBDelMBChars()

int WBDelMBChars	(	char *	pString,
		int	iCol,
		int	nDel,
		int *	piNewCol,
		char **	ppDeleted
	)

Delete a specified number of multi-byte characters from a string 'in place', starting at a specified column.

Parameters

pString	A pointer to a buffer containing a multi-byte character string. The string must terminate with a zero byte.
iCol	A zero-based column at which point to delete the text.
nDel	An integer indicating the number of multi-byte characters to delete. A negative number will delete 'backspace' style, starting with the PREVIOUS character. Positive deletes beginning with the character at 'iCol'.
piNewCol	An optional pointer to an integer that receives the new column that the cursor is on after the operation completes. May be NULL.
ppDeleted	An optional pointer to a char * that will be assigned a WBAlloc'd pointer to a string containing the deleted characters. May be NULL. The caller must free any non-NULL returned value via WBFree()

Returns: The number of deletions remaining (preserving the sign of 'nDel') after the operation completes.

This function performs the somewhat complicated 'delete a multi-byte character' functionality in a consistent AND column-based manner, so that a string that has multi-byte characters can be edited in the same way as a string that has characters with consistent length. It also returns the number of delete operations remaining.

In many cases, a series of 'backspaces' or 'deletes' may extend into a previous or subsequent line. In these cases, they must be handled in a separate call involving the previous or next line's multi-byte character buffer. The caller is responsible for handlnig this, as well as for collapsing the lines or joining them together.

If a 'ppDeleted' pointer value is specified, this function will store the deleted text in a buffer allocated via WBAlloc(). The caller must free any non-NULL value returned by this function using WBFree(). The data that is stored in this allocated buffer can be used to support 'undo' and 'redo'.

Header File: text_object.h

Definition at line 6820 of file text_object.c.

◆ WBGetMBCharPtr()

char* WBGetMBCharPtr	(	char *	pString,
		int	iCol,
		int *	pcbLen
	)

Obtain the pointer to a specific multi-byte character within a multi-byte character string, by specifying it's column.

Parameters

pString	A pointer to a buffer containing a multi-byte character string. The string must terminate with a zero byte.
iCol	A zero-based column at which point to return a pointer to the multi-byte character
pcbLen	A pointer to an integer that receives the length of the character being pointed to by the return value. This pointer may be NULL

Returns: A pointer to the multi-byte character located at the 'iCol' position within the string. If 'iCol' is out range, the return value will point to the terminating zero byte. On error, the return value will be NULL.

Header File: text_object.h

Definition at line 6994 of file text_object.c.

◆ WBGetMBColIndex()

int WBGetMBColIndex	(	const char *	pString,
		const char *	pChar
	)

Obtain the column index from a pointer within a multi-byte character string.

Parameters

pString	A pointer to a buffer containing a multi-byte character string. The string must terminate with a zero byte.
pChar	A (const) pointer to a character within 'pString'. This must be a pointer to the start of a valid UTF-8 character within 'pString'.

Returns: The zero-based column index of the character pointed to by 'pChar' within 'pString. If 'pChar' is out range, or points to an invalid character, the return value will be zero.

Header File: text_object.h

Definition at line 7026 of file text_object.c.

◆ WBGetMBLength()

int WBGetMBLength ( const char * pString )

Obtain the length of a multi-byte character string in 'characters' (not bytes)

Parameters

pString A pointer to a buffer containing a multi-byte character string. The string must terminate with a zero byte.

Returns: The length of the multi-byte character string in 'characters'

Header File: text_object.h

Definition at line 6984 of file text_object.c.

◆ WBInsertMBChars()

char* WBInsertMBChars	(	char *	pString,
		int	iCol,
		const char *	pszMBString,
		int	cbString,
		int	fTab,
		int	fOverwrite,
		int *	piNewCol,
		char **	ppInserted
	)

Insert multi-byte characters into a WBAlloc'd string, at a specified column.

Parameters

pString	A pointer to a WBAlloc'd buffer containing a multi-byte character string. The string must terminate with a zero byte.
iCol	A zero-based column at which point to insert the text.
pszMBString	A pointer to a buffer containing the multi-byte characters to insert. It must NOT contain any return or line feed characters. Tabs will be translated as specified. Other control characters will become spaces (including line feeds, if present)
cbString	The length of the multi-byte character string (in bytes, not characters), or -1 to use a terminating zero byte as 'end of string'
fTab	An integer indicating how tabs should be handled. A value of 0 indicates 'no tabs', '-1' is the 'default' tab, and any other value, the number of spaces that a tab will align with.
fOverwrite	Non-zero to 'overwrite' rather than insert the characters. Overwrite can extend the length of the string.
piNewCol	A pointer to an integer to receive the 0-based 'new' column at which the cursor is pointing after the insert. See 'WBSplitMBLine()' for a method to insert a line feed at this point.
ppInserted	An optional pointer to a char * that will be assigned a WBAlloc'd pointer to a string containing the inserted characters. May be NULL. The caller must free any non-NULL returned value via WBFree()

Returns: A pointer to a WBAlloc'd string containing the results. If different from 'pString', the 'pString' pointer value will no longer be valid. On error, it will return NULL

This function performs the somewhat complicated 'insert a multi-byte character' functionality in a consistent AND column-based manner, so that a string that has multi-byte characters can be edited in the same way as a string that has characters with consistent length. In this way, ANY multi-byte character that is available at a future point in time can be supported. The alternative would be to convert to "a unicode format", which may limit the character set that could be used; as an example, 16-bit unicode characters won't include characters that are available in the 24-bit Unicode character set. Having a ridiculously large bit-length for a single character is not much of a consolation, and so this function (and others) will deal with multiple byte characters as they are, in an independent manner.

It is the caller's responsibility to filter out line feed characters, and insert new lines into a line buffer.

If a 'ppInserted' pointer value is specified, this function will store the inserted text in a buffer allocated via WBAlloc(). The caller must free any non-NULL value returned by this function using WBFree(). The data that is stored in this allocated buffer can be used to support 'undo' and 'redo'.

Header File: text_object.h

Definition at line 6726 of file text_object.c.

◆ WBJoinMBLine()

char* WBJoinMBLine	(	char *	pString,
		int	iCol,
		const char *	pJoin
	)

Split a multi-byte characters into a WBAlloc'd string, at a specified column, terminating the original string at that column with a zero byte.

Parameters

pString	A pointer to a WBAlloc'd buffer containing a multi-byte character string. The string must terminate with a zero byte.
iCol	A 0-based column index value. If the value is greater than the length of 'pString', then 'pString' will be padded with spaces up to that column before 'joining'.
pJoin	A (const) poitner to a buffer containing a multi-byte character string, terminated with a zero byte. This

Returns: A pointer to a WBAlloc'd string containing the resulting 'join'ed string. If different from 'pString', the 'pString' pointer value will no longer be valid. On error, it will return NULL

This function will 'join' a 2nd string to an existing (WBAlloc'd) multi-byte character string, optionally at a specified column (padding it with white space, as needed). The 'pString' pointer must have been allocated via WBAlloc for this to function properly. However, the 'pJoin' string can be from any source.

The caller is expected to remove the subsequent string pointer from being the 'next' line, as needed, following the line join.

Definition at line 6783 of file text_object.c.

◆ WBSplitMBLine()

char* WBSplitMBLine	(	char *	pString,
		int	iCol
	)

Split a multi-byte characters into a WBAlloc'd string, at a specified column, terminating the original string at that column with a zero byte.

Parameters

pString	A pointer to a WBAlloc'd buffer containing a multi-byte character string. The string must terminate with a zero byte.
iCol	A zero-based column at which point to split the line.

Returns: A pointer to a WBAlloc'd string containing the next line to insert. On error, it will return NULL without any changes being made.

This function will 'split' a string at a particular column, returning a WBAlloc'd pointer to the 'remainder' of the line, which is intended to be inserted as a new line. The new line will NOT be indented, and leading white space will be left 'as-is'. Trailing white space on the original line, however, will automatically be trimmed.

The caller is expected to insert the returned string pointer as the 'next' line, following the line split. The caller is also responsible for any 'auto indent' functionality that might be needed for a line split.

Definition at line 6746 of file text_object.c.

Functions

Detailed Description

Function Documentation

◆ WBDelMBChars()

◆ WBGetMBCharPtr()

◆ WBGetMBColIndex()

◆ WBGetMBLength()

◆ WBInsertMBChars()

◆ WBJoinMBLine()

◆ WBSplitMBLine()