Simple text formatting

TFormattableText stores a text string as an instance of TText. TFormattableText provides constructors for passing the text string in as either a TText reference or a character string (char*). You can also set the text string with the SetText member function.

The TSimpleTextFormatter::Format function retrieves the text string contained by an instance of TFormattableText, and inserts it into a text instance that can then be inserted into the text template of a TParameterFormatter instance. You can also implement other ways to use the retrieved text.

The TSimpleTextFormatter::Scan function scans a specified range of a text instance, returning the text string as an instance of TFormattableText. It scans the text until it reaches the string stored in the TSimpleTextFormatter data member fTerminatingText. It does not scan in any part of the terminating string. By default, the terminating string is TASCII::kNull. You can change the terminating string by calling the SetTerminatingString member function.

You can also provide a text-ordering object if you want to implement language-sensitive matching for the terminating string. You must specify this object when you construct the formatter. By default, the formatter uses an instance of TBitwiseTextOrder for matching, which simply compares the UniChar values.

The following code shows how to use a TSimpleTextFormatter instance with a TParameterFormatter instance to scan and format a text message containing a text parameter.

  TSimpleTextFormatter* textFormatter;
  TFormattableText text;
  TParameterFormatter parameterFormatter;
  TFormattableParameterList parameters;
  TStandardText template( "Scan this text: XX " );
  TStandardText scanText( "Scan this text: Hello world! END" );
  
  TFormatResult formatResult;
  TScanResult scanResult;
  TStandardText formattedText;
  
  // Set up the text formatter with a terminating string and an ordering object.
  TStandardText terminatingText( "END" );
  textFormatter = new TSimpleTextFormatter( terminatingText );
  
  // Set up the parameter formatter.
  parameterFormatter.SetTemplate( template );
  parameterFormatter.SetParameterType( 0,"TFormattableText" );
  parameterFormatter.SetParameterFormat( TTextRange( 16, TTextCount(2) ), 0, 
                                   *textFormatter );
  
  // Set up the parameter list.
  parameters.SetParameter(0, text);
  
  // Scan a text string.
  parameterFormatter.Scan( scanText, TTextRange::GetMaximumRange(), parameters, 
                          scanResult );
  // The TFormattableText instance text now contains the string "Hello world! "
  
  // Format a text string.
  parameterFormatter.Format( parameters, formattedText, formatResult );
  
  // The TStandardText instance formattedText now contains the string
  // "Scan this text: Hello world! "
  
  delete textFormatter;