This module efficiently manages a collection of strings that have common
substrings. Collections with a high degree of commonality are stored in
much less space than as ordinary table of independent C strings.
To further save space, the "compressed" representation need not even
be loaded in the target's memory; see
isLoaded.
The total space available for the compressed representation of text strings
is limited to 64K characters; each string is represented by a 16-bit
"rope id".
typedef Text_Label |
|
config Text_isLoaded // module-wide |
|
Ensure character-strings are loaded in target memory
extern const Bool Text_isLoaded;
DETAILS
Character strings managed by this module are allocated together
with other character strings, and loaded to the target, when this
parameter is set to its default value true. If this parameter is
set to false, the character strings managed by Text are removed from
the application.
A consequence of setting this parameter to false is that all names
assigned to static instances are set to NULL, and cannot be displayed by
the code loaded to the target. Also, the Log Events that automatically
print instance names will print NULL for any static instance. The same
code would print the pointers to the names if this parameter is set to
true and 'isLoaded is set to 'false`.
ROV is not affected by this parameter and it will also correctly display
names of static instances in their modules' views. ROV detects these
names from the saved configuration files.
Module and event IDs are still unique and Log.Events within one module
have consecutive IDs.
config Text_nameEmpty // module-wide |
|
Default NULL instance name
extern const String Text_nameEmpty;
DETAILS
The name used if the instance's name has been set to NULL.
config Text_nameStatic // module-wide |
|
Default static instance name
extern const String Text_nameStatic;
DETAILS
The name of an instance if the name exists but it's not loaded
on the target.
config Text_nameUnknown // module-wide |
|
Default unknowable instance name
extern const String Text_nameUnknown;
DETAILS
The name of an instance if the module's instances are configured to
not have names.
Text_putLab() // module-wide |
|
Convert label to an ASCII character sequence
Int Text_putLab(
Types_Label *
lab,
Char **
bufp,
Int len);
ARGUMENTS
lab
address of the label to interpret
bufp
address of the output buffer pointer or NULL
If
bufp is
NULL, the label's characters are
output via
System.putch().
len
maximum number of characters to generate
If len is negative, the number of characters to be
generated is not limited.
DETAILS
This function converts a
Types.Label to a sequence of
ASCII characters, writes the characters to the supplied buffer,
updates the buffer pointer to point to the location after the last
output character, and returns the number of characters output.
No more than len characters will be output. If the label would
otherwise be longer, the output is truncated at the point where a
potential overflow is detected. The return value always reflects the
number of characters output, but it may be less than len.
Label structures can be initialized from any module's instance handle
using the module's
Mod_Handle_label() method. See
Types.Label for more information.
RETURNS
The return value always reflects the number of characters output,
but it may be less than len.
SEE
Text_putMod() // module-wide |
|
Convert module ID to its ASCII name
ARGUMENTS
mid
ID of the module
bufp
address of the output buffer pointer or NULL
If
bufp is
NULL, the module's name characters are
output via
System.putch().
len
maximum number of characters to generate
If len is negative, the number of characters to be
generated is not limited.
DETAILS
This function converts a
Types.ModuleId to a sequence of
ASCII characters, writes the characters to the supplied buffer,
updates the buffer pointer to point to the location after the last
output character, and returns the number of characters output.
No more than len characters will be output. If the module name would
otherwise be longer, the output is truncated at the point where a
potential overflow is detected. The return value always reflects the
number of characters output, but it may be less than len.
RETURNS
The return value always reflects the number of characters output,
but it may be less than len.
Text_putSite() // module-wide |
|
Convert call site structure to an ASCII character sequence
Int Text_putSite(
Types_Site *
site,
Char **
bufp,
Int len);
ARGUMENTS
site
address of the call site structure to interpret
bufp
address of the output buffer pointer or NULL
If
bufp is
NULL, the site's name characters are
output via
System.putch().
len
maximum number of characters to generate
If len is negative, the number of characters to be
generated is not limited.
DETAILS
This function converts a
Types.Site to a sequence of
ASCII characters, writes the characters to the supplied buffer,
updates the buffer pointer to point to the location after the last
output character, and returns the number of characters output.
No more than len characters will be output. If the sequence would
otherwise be longer, the output is truncated at the point where a
potential overflow is detected.
RETURNS
The return value always reflects the number of characters output,
but it may be less than len.
Module-Wide Built-Ins |
|
// Get this module's unique id
Bool Text_Module_startupDone();
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool Text_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Text_Module_getMask();
// Returns the diagnostics mask for this module
Void Text_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
config Text.isLoaded // module-wide |
|
Ensure character-strings are loaded in target memory
Text.isLoaded = Bool true;
DETAILS
Character strings managed by this module are allocated together
with other character strings, and loaded to the target, when this
parameter is set to its default value true. If this parameter is
set to false, the character strings managed by Text are removed from
the application.
A consequence of setting this parameter to false is that all names
assigned to static instances are set to NULL, and cannot be displayed by
the code loaded to the target. Also, the Log Events that automatically
print instance names will print NULL for any static instance. The same
code would print the pointers to the names if this parameter is set to
true and 'isLoaded is set to 'false`.
ROV is not affected by this parameter and it will also correctly display
names of static instances in their modules' views. ROV detects these
names from the saved configuration files.
Module and event IDs are still unique and Log.Events within one module
have consecutive IDs.
C SYNOPSIS
config Text.nameEmpty // module-wide |
|
Default NULL instance name
Text.nameEmpty = String "{empty-instance-name}";
DETAILS
The name used if the instance's name has been set to NULL.
C SYNOPSIS
config Text.nameStatic // module-wide |
|
Default static instance name
Text.nameStatic = String "{static-instance-name}";
DETAILS
The name of an instance if the name exists but it's not loaded
on the target.
C SYNOPSIS
config Text.nameUnknown // module-wide |
|
Default unknowable instance name
Text.nameUnknown = String "{unknown-instance-name}";
DETAILS
The name of an instance if the module's instances are configured to
not have names.
C SYNOPSIS
metaonly config Text.common$ // module-wide |
|
Common module configuration parameters
DETAILS
All modules have this configuration parameter. Its name
contains the '$' character to ensure it does not conflict with
configuration parameters declared by the module. This allows
new configuration parameters to be added in the future without
any chance of breaking existing modules.