Fork us on GitHub Follow us on Facebook Follow us on Twitter

Changes between Initial Version and Version 1 of StringAPI

2009-05-01T21:50:06Z (10 years ago)
Jiri Svoboda

The new and shiny API (t.m.)


  • StringAPI

    v1 v1  
     1= String API =
     3Recently HelenOS switched to a new string API. It is non-standard, but in many ways similar to the ANSI C string API.
     5 * [#CharacterRepertoire Character Repertoire and]
     6 * [#StringMetrics String Metrics]
     7 * [#EncodingDecoding Encoding and Decoding a Character]
     8 * [#OutputBuffers Output Buffers]
     9 * [#FunctionReference Function Reference]
     11== Character Repertoire and Encoding == #CharacterRepertoire
     13HelenOS uses the Universal Character Set or UCS (as defined by ISO/IEC 10646) for representing characters throughout the system. A single ''character'' is represented as `wchar_t` (32-bit). Normally all ''strings'' are represented in UTF-8 and null-terminated. A string is usually declared as `char *`. The API also has limited support for strings that are not null-terimanted (or sub-strings).
     15There is also limited support for ''wide strings''. These are encoded in UTF-32 and null-terminated. Wide strings can represent exactly the same characters like normal strings. However, with UTF-8 each character is encoded as one or more bytes. With UTF-32, which is used for the wide strings, each character is encoded as exactly four bytes.
     17== Character and String Literals ==
     19In source code non-ASCII characters should only be used in character and string literals. Keep in mind that HelenOS source files are encoded in UTF-8, too. Non-ASCII character literals need to be written as `L'x'`. String literals are written the usual way (`"string"`) and wide-string literals are written as `L"wide string"`.
     21== String Metrics == #StringMetrics
     23 * Size
     24 * Length
     25 * Width
     27== Encoding and Decoding a Character == #EncodingDecoding
     29 * str_decode()
     30 * chr_encode()
     32== Well-formed Strings ==
     34A string is considered ''well formed'' if and only if it is null-terminated and consists only of complete and valid UTF-8-encoded characters (i.e. it can be decoded with `str_decode()` without error). Unless stated otherwise, all strings passed to functions must be well-formed and all string functions produce well-formed strings.
     36== Output Buffers == #OutputBuffers
     38Whenever the user supplies an output buffer to a string function, they must also pass the size of this buffer to the function (it is always passed in the following argument). The buffer size ''must be greater than zero''. The function will always fill the buffer with a well-formed string. If the string produced does not fit in the buffer, the function will only store as many (complete) characters as possible and add the null terminator.
     40== Function Reference == #FunctionReference
     42 * str_size()
     43 * wstr_size()
     44 * str_lsize()
     45 * wstr_lsize()
     47 * str_length()
     48 * wstr_length()
     49 * str_nlength()
     50 * wstr_nlength()
     52 * str_cpy()
     53 * str_ncpy()
     54 * str_append()
     55 * str_dup()
     57 * wstr_nstr()
     59 * str_chr()
     60 * str_rchr()