Description

A Unicode (UTF-8) text string.

Typedefs
typedef const char *	VuoText
	A Unicode (UTF-8) text string.

Enumerations
enum	VuoTextTruncation { VuoTextTruncation_Beginning, VuoTextTruncation_End }
	Where to truncate text. More...

Functions
VuoText	VuoText_makeFromJson (json_object *js)
	Decodes the JSON object `js`, expected to contain a UTF-8 string, to create a new value.

json_object *	VuoText_getJson (const VuoText value)
	Encodes `value` as a JSON object.

char *	VuoText_getSummary (const VuoText value)
	Creates a new UTF-8 C string from `value`, or, if it's more than 50 Unicode characters long, creates an aposiopesis.

VuoText	VuoText_make (const char *unquotedString)
	Creates a VuoText value from an unquoted string (unlike `VuoText_makeFromString()`, which expects a quoted string).

size_t	VuoText_length (const VuoText text)
	Returns the number of Unicode characters in the text.

bool	VuoText_isLessThan (const VuoText text1, const VuoText text2)
	Returns true if text1 is ordered before text2 in a case-sensitive lexicographic ordering (which treats different UTF-8 encodings and Unicode character decompositions as equivalent).

size_t	VuoText_findFirstOccurrence (const VuoText string, const VuoText substring, const size_t startIndex)
	Returns the index (starting at 1) of the first instance of substring in string at index >= startIndex.

size_t	VuoText_findLastOccurrence (const VuoText string, const VuoText substring)
	Returns the index (starting at 1) of the last instance of substring in string.

VuoText	VuoText_substring (const VuoText string, int startIndex, int length)
	Returns the substring of `string` starting at index `startIndex` and spanning `length` Unicode characters.

VuoText	VuoText_append (VuoText *texts, size_t textsCount)
	Returns a string consisting of the elements in the `texts` array concatenated together.

VuoText *	VuoText_split (VuoText text, VuoText separator, bool includeEmptyParts, size_t *partsCount)
	Splits text into parts (basically the inverse of VuoText_append()).

VuoText	VuoText_makeWithMaxLength (const void *data, const size_t maxLength)
	Creates a VuoText value from an untrusted source (one that might not contain a NULL terminator within its memory page).

VuoText	VuoText_makeFromCFString (const void *cfString)
	Creates a VuoText value from a `CFStringRef`.

VuoText	VuoText_makeFromData (const unsigned char *data, const unsigned long size)
	Attempts to interpret `data` as UTF-8 text.

VuoText	VuoText_makeFromUtf32 (const uint32_t *data, size_t length)
	Create a new VuoText string from an array of UTF-32 values.

VuoText	VuoText_makeFromMacRoman (const char *string)
	Creates a new VuoText from a MacRoman-encoded string.

bool	VuoText_isEmpty (const VuoText text)
	Returns true if `text` is empty (is NULL or is non-NULL with zero length).

bool	VuoText_areEqual (const VuoText text1, const VuoText text2)
	Returns true if the two texts represent the same Unicode string (even if they use different UTF-8 encodings or Unicode character decompositions).

VuoList_VuoInteger	VuoText_findOccurrences (const VuoText string, const VuoText substring)
	Returns a list containing all occurrences of `substring` in `string`.

VuoText	VuoText_insert (const VuoText string, int startIndex, const VuoText newText)
	Returns a new string with `newText` inserted at the `startIndex`.

VuoText	VuoText_removeAt (const VuoText string, int startIndex, int length)
	Returns a new string where characters from `startIndex` to `startIndex` + `length` are removed.

VuoText	VuoText_replace (VuoText subject, VuoText stringToFind, VuoText replacement)
	Returns a new string in which each occurrence of `stringToFind` in `subject` has been replaced with `replacement`.

VuoText	VuoText_truncateWithEllipsis (const VuoText subject, int maxLength, VuoTextTruncation where)
	If `subject` is less than or equal to `maxLength` Unicode characters long, returns `subject`.

VuoText	VuoText_trim (const VuoText text)
	Returns a new string consisting of `text` without the whitespace at the beginning and end.

VuoText	VuoText_changeCase (const VuoText text, VuoTextCase textCase)
	Returns a new string with the `text` characters cased in the `textCase` style.

uint32_t *	VuoText_getUtf32Values (const VuoText text, size_t *length)
	Returns an array of unicode 32 bit decimal values for each character in a string.

char *	VuoText_format (const char *format,...) VUOTEXT_FORMAT_ATTRIBUTE
	Returns a new string formatted using the printf-style `format` string.

VuoText	VuoText_makeFromString (const char *str)
	Automatically generated function.

char *	VuoText_getString (const VuoText value)
	Automatically generated function.

void	VuoText_retain (VuoText value)
	Automatically generated function.

void	VuoText_release (VuoText value)
	Automatically generated function.

Typedef Documentation

typedef const char* VuoText

A Unicode (UTF-8) text string.

Enumeration Type Documentation

enum VuoTextTruncation

Where to truncate text.

Function Documentation

VuoText VuoText_append	(	VuoText *	texts,
		size_t	textsCount
	)

Returns a string consisting of the elements in the texts array concatenated together.

bool VuoText_areEqual	(	const VuoText	text1,
		const VuoText	text2
	)

Returns true if the two texts represent the same Unicode string (even if they use different UTF-8 encodings or Unicode character decompositions).

Either or both of the values may be NULL. NULL values are not equal to any string (including emptystring).

VuoText VuoText_changeCase	(	const VuoText	text,
		VuoTextCase	textCase
	)

Returns a new string with the text characters cased in the textCase style.

size_t VuoText_findFirstOccurrence	(	const VuoText	string,
		const VuoText	substring,
		const size_t	startIndex
	)

Returns the index (starting at 1) of the first instance of substring in string at index >= startIndex.

Returns 0 if substring is not found.

This function will find occurrences that consist of the same Unicode characters as substring, but won't find occurrences that consist of the same Unicode string decomposed into a different number of Unicode characters.

size_t VuoText_findLastOccurrence	(	const VuoText	string,
		const VuoText	substring
	)

Returns the index (starting at 1) of the last instance of substring in string.

Returns 0 if substring is not found.

This function will find occurrences that consist of the same Unicode characters as substring, but won't find occurrences that consist of the same Unicode string decomposed into a different number of Unicode characters.

VuoList_VuoInteger VuoText_findOccurrences	(	const VuoText	string,
		const VuoText	substring
	)

Returns a list containing all occurrences of substring in string.

This function will find occurrences that consist of the same Unicode characters as substring, but won't find occurrences that consist of the same Unicode string decomposed into a different number of Unicode characters.

char* VuoText_format	(	const char *	format,
			...
	)

Returns a new string formatted using the printf-style format string.

The caller is responsible for freeing the returned string.

struct json_object * VuoText_getJson ( const VuoText value )

read

Encodes value as a JSON object.

char* VuoText_getString ( const VuoText value )

Automatically generated function.

char * VuoText_getSummary ( const VuoText value )

Creates a new UTF-8 C string from value, or, if it's more than 50 Unicode characters long, creates an aposiopesis.

Example:: Hello World!

Example:: I would like to convey my gree...

uint32_t* VuoText_getUtf32Values	(	const VuoText	text,
		size_t *	length
	)

Returns an array of unicode 32 bit decimal values for each character in a string.

If conversion fails, length will be set to 0 null is returned. Otherwise an array is returned and length is set to the size of the array.

See Also: VuoText_makeFromUtf32

VuoText VuoText_insert	(	const VuoText	string,
		int	startIndex,
		const VuoText	newText
	)

Returns a new string with newText inserted at the startIndex.

startIndex is 1 indexed, not 0. If startIndex is less than 1, newText is inserted at the beginning of string. If startIndex is greater than string length, newText is appended to the ending of string.

bool VuoText_isEmpty ( const VuoText text )

Returns true if text is empty (is NULL or is non-NULL with zero length).

bool VuoText_isLessThan	(	const VuoText	text1,
		const VuoText	text2
	)

Returns true if text1 is ordered before text2 in a case-sensitive lexicographic ordering (which treats different UTF-8 encodings and Unicode character decompositions as equivalent).

size_t VuoText_length ( const VuoText text )

Returns the number of Unicode characters in the text.

VuoText VuoText_make ( const char * unquotedString )

Creates a VuoText value from an unquoted string (unlike VuoText_makeFromString(), which expects a quoted string).

VuoText VuoText_makeFromCFString ( const void * cfString )

Creates a VuoText value from a CFStringRef.

VuoText VuoText_makeFromData	(	const unsigned char *	data,
		const unsigned long	size
	)

Attempts to interpret data as UTF-8 text.

Returns NULL if data is not valid UTF-8 text (e.g., if it contains byte 0xfe or 0xff).

data is copied.

VuoText VuoText_makeFromJson ( json_object * js )

Decodes the JSON object js, expected to contain a UTF-8 string, to create a new value.

VuoText VuoText_makeFromMacRoman ( const char * string )

Creates a new VuoText from a MacRoman-encoded string.

VuoText VuoText_makeFromString ( const char * str )

Automatically generated function.

VuoText VuoText_makeFromUtf32	(	const uint32_t *	data,
		size_t	size
	)

Create a new VuoText string from an array of UTF-32 values.

Returns NULL if data is not valid UTF-32 text.

data is copied.

VuoText VuoText_makeWithMaxLength	(	const void *	data,
		const size_t	maxLength
	)

Creates a VuoText value from an untrusted source (one that might not contain a NULL terminator within its memory page).

Use this, for example, to safely handle a string that's part of a network packet.

This function scans up to maxLength bytes in data. If it finds a NULL terminator, it returns text up to and including the NULL terminator. If it doesn't find a NULL terminator, it returns maxLength characters followed by a NULL terminator.

This function does not yet respect multi-byte UTF8 characters. For now, only give it ASCII-7 input data.

void VuoText_release ( VuoText value )

Automatically generated function.

VuoText VuoText_removeAt	(	const VuoText	string,
		int	startIndex,
		int	length
	)

Returns a new string where characters from startIndex to startIndex + length are removed.

startIndex is 1 indexed, not 0.

VuoText VuoText_replace	(	VuoText	subject,
		VuoText	stringToFind,
		VuoText	replacement
	)

Returns a new string in which each occurrence of stringToFind in subject has been replaced with replacement.

stringToFind matches even if a different UTF-8 encoding or Unicode character decomposition is used.

void VuoText_retain ( VuoText value )

Automatically generated function.

VuoText * VuoText_split	(	VuoText	text,
		VuoText	separator,
		bool	includeEmptyParts,
		size_t *	partsCount
	)

Splits text into parts (basically the inverse of VuoText_append()).

VuoText VuoText_substring	(	const VuoText	string,
		int	startIndex,
		int	length
	)

Returns the substring of string starting at index startIndex and spanning length Unicode characters.

startIndex is indexed from 1, not 0.

If startIndex is past the end of string, returns the empty string.

If startIndex is before the beginning of string, deducts the number of characters before the beginning from length, and returns characters starting at the beginning of string.

If string has fewer than length characters from startIndex to the end of string, returns all characters from startIndex to the end of string.

VuoText VuoText_trim ( const VuoText text )

Returns a new string consisting of text without the whitespace at the beginning and end.

This function trims ASCII spaces, tabs, and linebreaks, but not other Unicode whitespace characters.

VuoText VuoText_truncateWithEllipsis	(	const VuoText	subject,
		int	maxLength,
		VuoTextTruncation	where
	)

If subject is less than or equal to maxLength Unicode characters long, returns subject.

If subject is greater than maxLength, truncates subject to maxLength characters and adds a Unicode ellipsis.

Description

Typedefs

Enumerations

Functions

Typedef Documentation

Enumeration Type Documentation

Function Documentation