Changes between Version 2 and Version 3 of StringAPI

Timestamp:

2009-05-02T12:28:20Z (15 years ago)

Author:

Jiri Svoboda

Comment:

String metrics

StringAPI

@@ -5 +5 @@
  * [#CharacterRepertoire Character Repertoire and Encoding]
  * [#StringMetrics String Metrics]
+ * [#PrefixFunctions Functions Operating on Prefixes]
  * [#EncodingDecoding Encoding and Decoding a Character]
  * [#OutputBuffers Output Buffers]
@@ -21 +22 @@
 == String Metrics == #StringMetrics
 
- * Size
- * Length
- * Width
+Unlike with an 8-bit encoding, there is not a 1:1:1 mapping between bytes in memory, characters and display cells on a monospace display. Therefore, three different metrics are needed:
+
+ * ''Size'' is the number of bytes to which the string is encoded, ''excluding'' the null terminator.
+ * ''Length'' is the number of ''characters'' in the string (i.e. the number of times we need to call str_decode() or chr_encode()). Again the null terminator is not counted.
+ * ''Width'' is the number of display cells on a monospace display the string will be rendered to.
 
 == Encoding and Decoding a Character == #EncodingDecoding
@@ -39 +42 @@
 
 == Function Reference == #FunctionReference
+
+Some functions operate on string prefixes. These have a name like `str_[n|l|w]op()`. Such a function only uses a prefix of the string limited by a metric, `n` for size, `l` for length, `w` for width.
 
  * str_size()