Difference between revisions of "AnsiString"
(→implementation: 32-bit, allegedly insert new external links [spam detection false positive]) |
m (Alextpp moved page Ansistring to AnsiString) |
||
(4 intermediate revisions by 2 users not shown) | |||
Line 16: | Line 16: | ||
An <syntaxhighlight lang="pascal" inline>AnsiString</syntaxhighlight> always entails some management data ''before'' the first character. | An <syntaxhighlight lang="pascal" inline>AnsiString</syntaxhighlight> always entails some management data ''before'' the first character. | ||
These are | These are | ||
+ | * a code page | ||
+ | * the size of a character | ||
* a reference count | * a reference count | ||
* the length of the string. | * the length of the string. | ||
{| class="wikitable" style="text-align: center; margin: auto;" | {| class="wikitable" style="text-align: center; margin: auto;" | ||
− | | <syntaxhighlight lang="pascal" inline>0</syntaxhighlight> | + | | <syntaxhighlight lang="pascal" inline>253</syntaxhighlight> |
− | | <syntaxhighlight lang="pascal" inline>0</syntaxhighlight> | + | | <syntaxhighlight lang="pascal" inline>233</syntaxhighlight> |
− | | <syntaxhighlight lang="pascal" inline>0</syntaxhighlight> | + | | <syntaxhighlight lang="pascal" inline>0</syntaxhighlight> |
− | | <syntaxhighlight lang="pascal" inline>1</syntaxhighlight> | + | | <syntaxhighlight lang="pascal" inline>1</syntaxhighlight> |
− | | <syntaxhighlight lang="pascal" inline>0</syntaxhighlight> | + | | <syntaxhighlight lang="pascal" inline>0</syntaxhighlight> |
− | | <syntaxhighlight lang="pascal" inline>0</syntaxhighlight> | + | | <syntaxhighlight lang="pascal" inline>0</syntaxhighlight> |
− | | <syntaxhighlight lang="pascal" inline>0</syntaxhighlight> | + | | <syntaxhighlight lang="pascal" inline>0</syntaxhighlight> |
− | | <syntaxhighlight lang="pascal" inline>3</syntaxhighlight> | + | | <syntaxhighlight lang="pascal" inline>1</syntaxhighlight> |
+ | | <syntaxhighlight lang="pascal" inline>0</syntaxhighlight> | ||
+ | | <syntaxhighlight lang="pascal" inline>0</syntaxhighlight> | ||
+ | | <syntaxhighlight lang="pascal" inline>0</syntaxhighlight> | ||
+ | | <syntaxhighlight lang="pascal" inline>3</syntaxhighlight> | ||
| <syntaxhighlight lang="pascal" inline>'F'</syntaxhighlight> | | <syntaxhighlight lang="pascal" inline>'F'</syntaxhighlight> | ||
| <syntaxhighlight lang="pascal" inline>'o'</syntaxhighlight> | | <syntaxhighlight lang="pascal" inline>'o'</syntaxhighlight> | ||
| <syntaxhighlight lang="pascal" inline>'o'</syntaxhighlight> | | <syntaxhighlight lang="pascal" inline>'o'</syntaxhighlight> | ||
− | | <syntaxhighlight lang="pascal" inline>#0</syntaxhighlight> | + | | <syntaxhighlight lang="pascal" inline>#0</syntaxhighlight> |
|- | |- | ||
+ | ! colspan="2" | code page | ||
+ | ! colspan="2" | maximum character size | ||
! colspan="4" | reference count | ! colspan="4" | reference count | ||
! colspan="4" | length | ! colspan="4" | length | ||
Line 37: | Line 45: | ||
! complimentary Null | ! complimentary Null | ||
|- | |- | ||
− | | colspan=" | + | | colspan="13" style="text-align: right;" | pointer points here ⤴ |
| colspan="3" | | | colspan="3" | | ||
|+ <syntaxhighlight lang="pascal" inline>AnsiString</syntaxhighlight> memory layout sample ([[32 bit|32-bit]] platform) | |+ <syntaxhighlight lang="pascal" inline>AnsiString</syntaxhighlight> memory layout sample ([[32 bit|32-bit]] platform) | ||
Line 44: | Line 52: | ||
In Pascal, an <syntaxhighlight lang="pascal" inline>AnsiString</syntaxhighlight> may contain <syntaxhighlight lang="pascal" inline>#0</syntaxhighlight> characters. | In Pascal, an <syntaxhighlight lang="pascal" inline>AnsiString</syntaxhighlight> may contain <syntaxhighlight lang="pascal" inline>#0</syntaxhighlight> characters. | ||
− | + | An <syntaxhighlight lang="pascal" inline>AnsiString</syntaxhighlight> can furthermore be associated with a code page (since [[FPC New Features 3.0.0#Support for codepage-aware strings|3.0.0]]). | |
== application == | == application == | ||
Line 54: | Line 62: | ||
Characters in <syntaxhighlight lang="pascal" inline>AnsiString</syntaxhighlight> have a 1-based index. | Characters in <syntaxhighlight lang="pascal" inline>AnsiString</syntaxhighlight> have a 1-based index. | ||
<syntaxhighlight lang="pascal" inline>myAnsiString[1]</syntaxhighlight> refers to the first character. | <syntaxhighlight lang="pascal" inline>myAnsiString[1]</syntaxhighlight> refers to the first character. | ||
+ | {{Note|The linear character index is only guaranteed to work for strings that have a maximum character size of <syntaxhighlight lang="pascal" inline>1</syntaxhighlight>. That means, using an integer index for example on an UTF-8 encoded string (not exclusively containing ASCII characters) will produce erroneous results.}} | ||
+ | |||
The {{Doc|package=RTL|unit=system|identifier=length|text=<syntaxhighlight lang="pascal" inline>length</syntaxhighlight> function}}, and for that matter also <syntaxhighlight lang="pascal" inline>high</syntaxhighlight>, will return a string’s length by examining the length data field. | The {{Doc|package=RTL|unit=system|identifier=length|text=<syntaxhighlight lang="pascal" inline>length</syntaxhighlight> function}}, and for that matter also <syntaxhighlight lang="pascal" inline>high</syntaxhighlight>, will return a string’s length by examining the length data field. | ||
Line 67: | Line 77: | ||
== see also == | == see also == | ||
* [[Character and string types]] | * [[Character and string types]] | ||
− | * [https://freepascal.org/docs-html/current/ref/refsu9.html#x32-370003.2.4 Ansistrings] in the reference guide | + | * [https://www.freepascal.org/docs-html/current/ref/refsu9.html#x32-370003.2.4 Ansistrings] in the reference guide |
+ | * [https://www.freepascal.org/docs-html/current/prog/progsu161.html#x205-2160008.2.7 Ansistrings] in the programmer’s guide | ||
[[Category: Data types]] | [[Category: Data types]] |
Latest revision as of 13:27, 22 December 2023
│ English (en) │
AnsiString
is a variable-length string data type.
It can store characters that have a size of one Byte.
implementation
In FPC an AnsiString
is implemented as a pointer.
It is a managed data type.
As such it is initialized with nil
as soon as it enters the scope.
Memory for the character sequence is dynamically allocated and freed.
An AnsiString
points to the first character.
This facilitates interfacing to libraries or foreign functions expecting pChar
strings.
For that, an AnsiString
always concludes with a null Byte.
In Pascal, this terminating null Byte has no significance as to the string’s value (including its length).
An AnsiString
always entails some management data before the first character.
These are
- a code page
- the size of a character
- a reference count
- the length of the string.
253
|
233
|
0
|
1
|
0
|
0
|
0
|
1
|
0
|
0
|
0
|
3
|
'F'
|
'o'
|
'o'
|
#0
|
code page | maximum character size | reference count | length | payload | complimentary Null | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
pointer points here ⤴ |
Only the length field has significance in Pascal.
In Pascal, an AnsiString
may contain #0
characters.
An AnsiString
can furthermore be associated with a code page (since 3.0.0).
application
The data type AnsiString
can be used like any other string data type.
You may assign string literals to an AnsiString
variable as normal.
String values can be compared (=
) just as usual.
The entire pointer-characteristic is transparent.
Characters in AnsiString
have a 1-based index.
myAnsiString[1]
refers to the first character.
1
. That means, using an integer index for example on an UTF-8 encoded string (not exclusively containing ASCII characters) will produce erroneous results.The length
function, and for that matter also high
, will return a string’s length by examining the length data field.
Because an AnsiString
is essentially a pointer, copying strings of this type is fast, since only the reference is copied and the reference count increased.
Modifications may trigger a COW.
caveats
- The compiler directive
{$longStrings on}
(or{$H+}
) aliasesstring
(without a specified length) toAnsiString
. AnsiString
as a managed data type introduces a certain overhead. See Avoiding implicit try finally section for more explanations.- The
sizeOf
value of anAnsiString
variable is merely the size of a pointer. - Assigning an empty string
''
to anAnsiString
variable will in fact assignnil
to the variable and, if the reference count hit zero, release underlying memory (if any was previously allocated at all). Empty strings are not stored as described above.
see also
- Character and string types
- Ansistrings in the reference guide
- Ansistrings in the programmer’s guide