EasyGUI  v0.1
Platform independent GUI Library
String functions

String functions with UNICODE support. More...

Modules

 Unicode processing
 Unicode processing functions with UTF-8 character encoding.
 

Data Structures

struct  GUI_STRING_t
 String structure for parsing characters. More...
 

Functions

size_t gui_string_length (const GUI_Char *src)
 Return length of string. More...
 
size_t gui_string_lengthtotal (const GUI_Char *src)
 Return total number of bytes required for string. More...
 
GUI_Chargui_string_copy (GUI_Char *dst, const GUI_Char *src)
 Copy string from source to destination no matter of GUI_USE_UNICODE selection. More...
 
GUI_Chargui_string_copyn (GUI_Char *dst, const GUI_Char *src, size_t len)
 Copy string from source to destination with selectable number of bytes. More...
 
int gui_string_compare (const GUI_Char *s1, const GUI_Char *s2)
 Compare 2 strings. More...
 
uint8_t gui_string_isprintable (uint32_t ch)
 Check if character is printable. More...
 
uint8_t gui_string_prepare (GUI_STRING_t *s, const GUI_Char *str)
 Prepare string before it can be used with gui_string_getch or gui_string_getchreverse functions. More...
 
uint8_t gui_string_getch (GUI_STRING_t *str, uint32_t *out, uint8_t *len)
 Get next decoded character from source string. More...
 
uint8_t gui_string_getchreverse (GUI_STRING_t *str, uint32_t *out, uint8_t *len)
 Get character by character from end of string up. More...
 
uint8_t gui_string_gotoend (GUI_STRING_t *str)
 Set character pointer to the last character in sequence. More...
 

Detailed Description

String functions with UNICODE support.

Function Documentation

int gui_string_compare ( const GUI_Char s1,
const GUI_Char s2 
)

Compare 2 strings.

Parameters
[in]*s1First string address
[in]*s2Second string address
Return values
0Strings are the same
!=0Strings are not the same
GUI_Char* gui_string_copy ( GUI_Char dst,
const GUI_Char src 
)

Copy string from source to destination no matter of GUI_USE_UNICODE selection.

Parameters
[out]*dstDestination memory address
[in]*srcSource memory address
Return values
Pointerto destination memory
See also
gui_string_copyn
GUI_Char* gui_string_copyn ( GUI_Char dst,
const GUI_Char src,
size_t  len 
)

Copy string from source to destination with selectable number of bytes.

Parameters
[out]*dstDestination memory address
[in]*srcSource memory address
[in]lenNumber of bytes to copy
Return values
Pointerto destination memory
See also
gui_string_copy
uint8_t gui_string_getch ( GUI_STRING_t s,
uint32_t *  out,
uint8_t *  len 
)

Get next decoded character from source string.

GUI_Char myStr[] = "EasyGUI\xDF\x8F\xDF\x8F"; //Source string to check
GUI_STRING_t s; //Create string variable
uint32_t ch; //Output character
uint8_t i; //Number of bytes required for character generation
//GUI_USE_UNICODE = 1: string length = 9; Length total: 11
//GUI_USE_UNICODE = 0: string length = 11; Length total: 11
gui_string_prepare(&s, myStr); //Prepare string for reading
while (gui_string_getch(&s, &ch, &i)) { //Go through entire string
printf("I: %d, ch %c (%d)\r\n", (int)i, ch, (int)ch); //Print character by character
}
Note
When GUI_USE_UNICODE is set to 1, multiple bytes may be used for single character
Parameters
[in,out]*sPointer to GUI_STRING_t structure with input string. Function will internally change pointer of actual string where it points to to next character
[out]*outPointer to output memory where output character will be saved
[out]*lenPointer to output memory where number of bytes for string will be saved
Return values
1Character decoded OK
0Error with character decode process or string has reach the end
See also
gui_string_getchreverse
uint8_t gui_string_getchreverse ( GUI_STRING_t str,
uint32_t *  out,
uint8_t *  len 
)

Get character by character from end of string up.

Note
Functionality is the same as gui_string_getch except order is swapped
String must be at the last character before function is first time called
//TODO: Update code!
GUI_Char myStr[] = "EasyGUI\xDF\x8F\xDF\x8F"; //Source string to check
GUI_STRING_t s; //Create string variable
uint32_t ch; //Output character
uint8_t i; //Number of bytes required for character generation
//GUI_USE_UNICODE = 1: string length = 9; Length total: 11
//GUI_USE_UNICODE = 0: string length = 11; Length total: 11
gui_string_prepare(&s, myStr); //Prepare string for reading
gui_string_gotoend(&ptr); //Go to last character of string
while (gui_string_getchreverse(&s, &ch, &i)) { //Go through entire string
printf("I: %d, ch %c (%d)\r\n", (int)i, ch, (int)ch); //Print character by character
}
Note
When GUI_USE_UNICODE is set to 1, multiple bytes may be used for single character
Parameters
[in,out]*strPointer to GUI_STRING_t structure with input string. Function will internally change pointer of actual string where it points to to next character
[out]*outPointer to output memory where output character will be saved
[out]*lenPointer to output memory where number of bytes for string will be saved
Return values
1Character decoded OK
0Error with character decode process or string has reach the start
See also
gui_string_getch, gui_string_gotoend
uint8_t gui_string_gotoend ( GUI_STRING_t str)

Set character pointer to the last character in sequence.

Parameters
[in,out]*strPointer to GUI_STRING_t structure with string informations
Return values
1Pointer set to last character
0Pointer was not set to last character
See also
gui_string_getchreverse
uint8_t gui_string_isprintable ( uint32_t  ch)

Check if character is printable.

Parameters
[in]chFirst memory address
Return values
1Character is printable
0Character is not printable
size_t gui_string_length ( const GUI_Char src)

Return length of string.

Example input string: EasyGUI\xDF\x8F

  1. When GUI_USE_UNICODE is set to 1, function will try to parse unicode characters and will return 8 on top input string
  2. When GUI_USE_UNICODE is set to 0, function will count all the bytes until string end is reached and will return 9 on top input string
Parameters
[in]*srcPointer to source string to get length
Return values
Numberof visible characters in string
See also
gui_string_lengthtotal
size_t gui_string_lengthtotal ( const GUI_Char src)

Return total number of bytes required for string.

Note
When GUI_USE_UNICODE is set to 0, this function returns the same as gui_string_length
Parameters
[in]*srcPointer to source string to get length
Return values
Numberof visible characters in string
See also
gui_string_length
uint8_t gui_string_prepare ( GUI_STRING_t s,
const GUI_Char str 
)

Prepare string before it can be used with gui_string_getch or gui_string_getchreverse functions.

Parameters
[in,out]*sPointer to GUI_STRING_t as base string object
[in]*strPointer to GUI_Char with string used for manupulation
Return values
1String prepared and ready to use
0String was tno prepared