Vuo  2.0.0
Macros | Enumerations | Functions | Variables

Description

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)
 
json_objectVuoText_getJson (const VuoText value)
 
char * VuoText_getSummary (const VuoText value)
 
VuoText VuoText_make (const char *unquotedString)
 
size_t VuoText_length (const VuoText text)
 
bool VuoText_isLessThan (const VuoText text1, const VuoText text2)
 
bool VuoText_isLessThanCaseInsensitive (const VuoText text1, const VuoText text2)
 
bool VuoText_isLessThanNumeric (const VuoText text1, const VuoText text2)
 
bool VuoText_compare (VuoText text1, VuoTextComparison comparison, VuoText text2)
 
size_t VuoText_findFirstOccurrence (const VuoText string, const VuoText substring, const size_t startIndex)
 
size_t VuoText_findLastOccurrence (const VuoText string, const VuoText substring)
 
VuoText VuoText_substring (const VuoText string, int startIndex, int length)
 
VuoText VuoText_append (VuoText *texts, size_t textsCount)
 
VuoTextVuoText_split (VuoText text, VuoText separator, bool includeEmptyParts, size_t *partsCount)
 
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). More...
 
VuoText VuoText_makeFromCFString (const void *cfString)
 Creates a VuoText value from a CFStringRef. More...
 
VuoText VuoText_makeFromData (const unsigned char *data, const unsigned long size)
 Attempts to interpret data as UTF-8 text. More...
 
VuoText VuoText_makeFromUtf32 (const uint32_t *data, size_t length)
 Create a new VuoText string from an array of UTF-32 values. More...
 
VuoText VuoText_makeFromMacRoman (const char *string)
 Creates a new VuoText from a MacRoman-encoded string. More...
 
size_t VuoText_byteCount (const VuoText text)
 Returns the number of bytes in the text, not including the null terminator. More...
 
bool VuoText_isEmpty (const VuoText text)
 Returns true if text is empty (is NULL or is non-NULL with zero length). More...
 
bool VuoText_isPopulated (const VuoText text)
 Returns true if text is not empty. More...
 
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). More...
 
VuoList_VuoInteger VuoText_findOccurrences (const VuoText string, const VuoText substring)
 Returns a list containing all occurrences of substring in string. More...
 
VuoText VuoText_insert (const VuoText string, int startIndex, const VuoText newText)
 Returns a new string with newText inserted at the startIndex. More...
 
VuoText VuoText_removeAt (const VuoText string, int startIndex, int length)
 Returns a new string where characters from startIndex to startIndex + length are removed. More...
 
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. More...
 
VuoText VuoText_truncateWithEllipsis (const VuoText subject, int maxLength, VuoTextTruncation where)
 If subject is less than or equal to maxLength Unicode characters long, returns subject. More...
 
VuoText VuoText_trim (const VuoText text)
 Returns a new string consisting of text without the whitespace at the beginning and end. More...
 
VuoText VuoText_changeCase (const VuoText text, VuoTextCase textCase)
 Returns a new string with the text characters cased in the textCase style. More...
 
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. More...
 
char * VuoText_format (const char *format,...) VUOTEXT_FORMAT_ATTRIBUTE
 Returns a new string formatted using the printf-style format string. More...
 

Variables

const typedef char * VuoText
 A Unicode (UTF-8) text string. More...
 
VuoText VuoText_makeFromString (const char *str)
 Automatically generated function. More...
 
char * VuoText_getString (const VuoText value)
 Automatically generated function. More...
 
void VuoText_retain (VuoText value)
 Automatically generated function. More...
 
void VuoText_release (VuoText value)
 Automatically generated function. More...
 

Enumeration Type Documentation

◆ VuoTextTruncation

Where to truncate text.

Definition at line 42 of file VuoText.h.

Function Documentation

◆ VuoText_append()

VuoText VuoText_append ( VuoText texts,
size_t  textsCount 
)

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

Definition at line 740 of file VuoText.c.

◆ VuoText_areEqual()

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).

Definition at line 394 of file VuoText.c.

◆ VuoText_byteCount()

size_t VuoText_byteCount ( const VuoText  text)

Returns the number of bytes in the text, not including the null terminator.

Definition at line 364 of file VuoText.c.

◆ VuoText_changeCase()

VuoText VuoText_changeCase ( const VuoText  text,
VuoTextCase  textCase 
)

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

Definition at line 1018 of file VuoText.c.

◆ VuoText_compare()

bool VuoText_compare ( VuoText  text1,
VuoTextComparison  comparison,
VuoText  text2 
)

Returns true if text1 matches text2 based on comparison.

text1 is the subject of the comparison and text2 is the object. For example, if the comparison is "begins with", this function checks if text1 begins with text2.

Definition at line 486 of file VuoText.c.

◆ VuoText_findFirstOccurrence()

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.

Definition at line 590 of file VuoText.c.

◆ VuoText_findLastOccurrence()

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.

Definition at line 624 of file VuoText.c.

◆ VuoText_findOccurrences()

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.

Definition at line 662 of file VuoText.c.

◆ VuoText_format()

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.

Definition at line 961 of file VuoText.c.

◆ VuoText_getJson()

struct json_object * VuoText_getJson ( const VuoText  value)

Encodes value as a JSON object.

Definition at line 52 of file VuoText.c.

◆ VuoText_getString()

char* VuoText_getString ( const VuoText  value)

Automatically generated function.

◆ VuoText_getSummary()

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...

Definition at line 100 of file VuoText.c.

◆ VuoText_getUtf32Values()

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. Caller is responsible for freeing the returned array.

See also
VuoText_makeFromUtf32

Definition at line 1115 of file VuoText.c.

◆ VuoText_insert()

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.

Definition at line 901 of file VuoText.c.

◆ VuoText_isEmpty()

bool VuoText_isEmpty ( const VuoText  text)

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

Definition at line 375 of file VuoText.c.

◆ VuoText_isLessThan()

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).

Definition at line 453 of file VuoText.c.

◆ VuoText_isLessThanCaseInsensitive()

bool VuoText_isLessThanCaseInsensitive ( const VuoText  text1,
const VuoText  text2 
)

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

Definition at line 463 of file VuoText.c.

◆ VuoText_isLessThanNumeric()

bool VuoText_isLessThanNumeric ( const VuoText  text1,
const VuoText  text2 
)

Returns true if the number in text1 is less than the number in text2.

Definition at line 472 of file VuoText.c.

◆ VuoText_isPopulated()

bool VuoText_isPopulated ( const VuoText  text)

Returns true if text is not empty.

Definition at line 383 of file VuoText.c.

◆ VuoText_length()

size_t VuoText_length ( const VuoText  text)

Returns the number of Unicode characters in the text.

Definition at line 347 of file VuoText.c.

◆ VuoText_make()

VuoText VuoText_make ( const char *  unquotedString)

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

Definition at line 127 of file VuoText.c.

◆ VuoText_makeFromCFString()

VuoText VuoText_makeFromCFString ( const void *  cfString)

Creates a VuoText value from a CFStringRef.

Definition at line 180 of file VuoText.c.

◆ VuoText_makeFromData()

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.

Definition at line 277 of file VuoText.c.

◆ VuoText_makeFromJson()

VuoText VuoText_makeFromJson ( json_object js)

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

Definition at line 40 of file VuoText.c.

◆ VuoText_makeFromMacRoman()

VuoText VuoText_makeFromMacRoman ( const char *  string)

Creates a new VuoText from a MacRoman-encoded string.

Definition at line 327 of file VuoText.c.

◆ VuoText_makeFromString()

VuoText VuoText_makeFromString ( const char *  str)

Automatically generated function.

◆ VuoText_makeFromUtf32()

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.

Definition at line 295 of file VuoText.c.

◆ VuoText_makeWithMaxLength()

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.

If data ends with a NULL terminator, this function simply copies it into a new VuoText instance.

If data does not end with a NULL terminator, 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.

If data is in a multi-byte UTF8 character sequence when maxLength is reached, the sequence will be terminated partway, probably resulting in an invalid UTF8 sequence.

Definition at line 152 of file VuoText.c.

◆ VuoText_release()

void VuoText_release ( VuoText  value)

Automatically generated function.

◆ VuoText_removeAt()

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.

Definition at line 933 of file VuoText.c.

◆ VuoText_replace()

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.

Definition at line 855 of file VuoText.c.

◆ VuoText_retain()

void VuoText_retain ( VuoText  value)

Automatically generated function.

◆ VuoText_split()

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

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

Definition at line 767 of file VuoText.c.

◆ VuoText_substring()

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.

Definition at line 698 of file VuoText.c.

◆ VuoText_trim()

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.

See also
VuoStringUtilities::trim

Definition at line 984 of file VuoText.c.

◆ VuoText_truncateWithEllipsis()

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.

Definition at line 65 of file VuoText.c.

Variable Documentation

◆ VuoText

const typedef char* VuoText

A Unicode (UTF-8) text string.

Definition at line 27 of file VuoText.h.