Click above to get retro games delivered to your door ever month!

 char                String data type
------------------------------------------------------------------------------
 Syntax
   char[( <width> )]

 Arguments
   <width> is an optional width specifier.

 Features
   +----------------------------------------------------------------------+
   | Category             | character string                              |
   | Size                 | 1 to 256 bytes (last one is always zero)      |
   | Range                | any ASCII character                           |
   | Parameter: value     | yes                                           |
   | Parameter: reference | yes                                           |
   | Parameter: const     | yes                                           |
   | Return               | yes                                           |
   +----------------------------------------------------------------------+

 Description
   The char datatype is for storing short to medium long text,
   represented by a string of characters. Character variables are sequences
   of characters terminated by the ASCII NULL character (0).

   Character variables may not exceed 255 characters in length. The
   maximum length of a character variable can be set through the width
   specifier. The length of the string that can be held by a variable
   declared as char( 20 ) is maximed at 20 characters (the terminating
   zero is not counted and makes the full real length of the string 21
   characters). If width is not specified, then the variable has the
   default width of 255. Care must be taken to avoid assigning a string
   whose length exceeds the capacity of the variable.

   It is important to realize that a string assignment via a dereferenced
   ptr( char ) is a memory copy operation, that may extend to the
   declared length of the source string, or 255 bytes when the size is
   non-declared. Code like in the fragment below can result in fatal
   memory overwrites.

   vardef
      ptr( char ) pString
      char        cBuffer
      char        cText
   enddef
   cText := replicate( "X", 255 ) // use the variable to its full length
   pString := &cBuffer            // initialize the pointer
   pString += 20                  // move the pointer within the buffer

   At this stage pString points to the 21th byte in cBuffer, leaving
   less than 255 bytes of allocated space to utilize for copying via
   pString. If subsequently a 255 bytes string is copied to cBuffer via
   the pointer pString

   *pString := cText              // this writes behind the end of cBuffer

   then the copy operation overruns the space allocated for the cBuffer
   variable, overwriting anything that comes behind it, possibly resulting
   in a system crash.

 Example
   #define EXAMPLE_DATATYPE
   #include example.hdr

   proc Test_char
   vardef
      char        cString1      // length is 255 + 1 bytes
      char( 20 )  cString2      // length is  20 + 1 bytes
      char(  1 )  cString3      // length is   1 + 1 bytes
      ptr( byte ) pChar
   enddef
   cString1 := "This variable can have a long string"
   cString2 := space( 20 )     // maximum length assigned
   cString3 := ""
   cString3 := "."             // maximum length assigned
   ? cString1 + cString3
   
   // the most efficient way of clearing a string is done via a ptr( byte )
   pChar := &cString1
   *pChar := 0   // terminate the string at its beginning via pointer
   ? cString1    // nothing is printed here
   endproc

   proc main
   Test_char()
   endproc