class ImplementationNotes "Implementation Notes"
extends Modelica.Icons.Information;
annotation (Documentation(info = "<html>\n<p>\nBelow the major design decisions of this library are summarized.\n</p>\n<ul>\n<li> <strong>C-Function Interface</strong><br>\n This library contains several interfaces to C-functions in order\n to operate with the environment. As will become clear, it is usually\n required that a Modelica tool vendor provides an implementation\n of these C-functions that are suited for his environment.\n In directory \"Modelica/Resources/C-Sources\" a reference implementation\n is given for Microsoft Windows Systems and for POSIX environments.\n The files \"ModelicaInternal.c\" and \"ModelicaStrings.c\" can be\n used as a basis for the integration in the vendors environment.<br> </li>\n<li> <strong>Character Encoding</strong><br>\n The representation of characters is different in operating systems.\n The more modern ones (e.g., Windows-NT) use an early variant of\n Unicode (16 bit per character)\n other (e.g., Windows-ME) use 8-bit encoding. Also 32 bit per character\n and multi-byte representations are in use. This is important, since e.g.,\n Japanese Modelica users need Unicode representation. The design in this\n library is done in such a way that a basic set of calls to the operating\n system hides the actual character representation. This means, that all\n functions of this package can be used independent from the underlying\n character representation.<br>\n The C-interface of the Modelica language provides only an 8-bit\n character encoding passing mechanism of strings. As a result, the\n reference implementation in \"Modelica.Utilities\\C-Source\" needs to\n be adapted to the character representation supported in the\n Modelica vendor environment.<br> </li>\n<li> <strong>Internal String Representation</strong><br>\n The design of this package was made in order that string handling\n is convenient. This is in contrast to, e.g., the C-language, where\n string handling is inconvenient, cumbersome and error prone, but on the\n other hand is in some sense \"efficient\".\n The standard reference implementation in \"Modelica.Utilities\\C-Source\"\n is based on the standard C definition of a string, i.e., a pointer to\n a sequence of characters, ended with a null terminating character.\n In order that the string handling in this package is convenient,\n some assumptions have been made, especially, that the access to\n a substring is efficient (O(1) access instead of O(n) as in standard C).\n This allows to hide string pointer arithmetic from the user.\n In such a case, a similar efficiency as in C can be expected for\n most high level operations, such as find, sort, replace.\n The \"efficient character access\" can be reached if, e.g.,\n the number of characters\n are stored in a string, and the length of a character is fixed,\n say 16 or 32 bit (if all Unicode characters shall be represented).\n A vendor should adapt the reference implementation in this\n respect.<br> </li>\n<li> <strong>String copy = pointer copy</strong><br>\n The Modelica language has no mechanism to change a character\n of a string. When a string has to be modified, the only way\n to achieve this is to generate it newly. The advantage is that\n a Modelica tool can treat a string as a constant entity and\n can replace (expensive) string copy operations by pointer\n copy operations. For example, when sorting a set of strings\n the following type of operations occur:\n <pre>\n String s[:], s_temp;\n ...\n s_temp := s[i];\n s[i] := s[j];\n s[j] := s_temp;\n </pre>\n Formally, three strings are copied. Due to the feature\n sketched above, a Modelica tool can replace this\n copy operation by pointer assignments, a very \"cheap\"\n operation. The Modelica.Utilities functions will perform\n efficiently, if such types of optimizations are supported\n by the tool.</li>\n</ul>\n</html>"));
end ImplementationNotes;