12 <concept id="GUID-F46D5A5B-EC44-53B0-9A11-886735B28610" xml:lang="en"><title>How to

    12 <concept id="GUID-F46D5A5B-EC44-53B0-9A11-886735B28610" xml:lang="en"><title>How to use the modifiable pointer descriptor — TPtr</title><shortdesc>Modifiable pointer descriptors are useful for referencing

    13 use the modifiable pointer descriptor — TPtr</title><shortdesc>Modifiable pointer descriptors are useful for referencing strings

    13 strings or data which can be accessed and changed.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 or data which can be accessed and changed.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    16 <li id="GUID-80F50BD5-A919-5EB3-B28E-4BDF7A2A0121"><p>For text data, it is

    15 <li id="GUID-80F50BD5-A919-5EB3-B28E-4BDF7A2A0121"><p>For text data,

    17 usual to construct a <codeph>TPtr</codeph> type and allow the appropriate

    16 it is usual to construct a <codeph>TPtr</codeph> type and allow the

    18 variant, either a <codeph>TPtr</codeph> or a <codeph>TPtrC</codeph> to be

    17 appropriate variant, either a <codeph>TPtr</codeph> or a <codeph>TPtrC</codeph> to be selected at build time.</p> </li>

    19 selected at build time.</p> </li>

    18 <li id="GUID-965CB6DC-DE3E-5744-A6D8-10C9A0567011"><p>For binary data,

    20 <li id="GUID-965CB6DC-DE3E-5744-A6D8-10C9A0567011"><p>For binary data, an

    19 an explicit <codeph>TPtr8</codeph> is used.</p> </li>

    21 explicit <codeph>TPtr8</codeph> is used.</p> </li>

    20 <li id="GUID-40B8DB60-33DB-56D3-BDE7-263B1B48840E"><p>It is rare to

    22 <li id="GUID-40B8DB60-33DB-56D3-BDE7-263B1B48840E"><p>It is rare to use an

    21 use an explicit <codeph>TPtr16</codeph>.</p> </li>

    23 explicit <codeph>TPtr16</codeph>.</p> </li>

    25 <section id="GUID-AEBBFA2C-D87D-48F8-ADBF-0A042F371EC1"><title>Constructing a TPtr</title> <p>A modifiable pointer descriptor

    23 <section id="GUID-AEBBFA2C-D87D-48F8-ADBF-0A042F371EC1"><title>Constructing

    26 can be constructed in a number of ways:</p> <ul>

    24 a TPtr</title> <p>A modifiable pointer descriptor can be constructed

    27 <li id="GUID-C3767C93-A5BA-5B09-A90D-FAD74E9CDC3F"><p>another modifiable pointer

    25 in a number of ways:</p> <ul>

    28 descriptor.</p> </li>

    26 <li id="GUID-C3767C93-A5BA-5B09-A90D-FAD74E9CDC3F"><p>another modifiable

    27 pointer descriptor.</p> </li>

    31 <li id="GUID-2F09FD0B-7FE7-5D4E-B353-233B2609F9FC"><p>from an explicit pointer

    30 <li id="GUID-2F09FD0B-7FE7-5D4E-B353-233B2609F9FC"><p>from an explicit

    32 into memory and specifying a maximum length.</p> </li>

    31 pointer into memory and specifying a maximum length.</p> </li>

    33 <li id="GUID-F9C4E446-B390-56AD-8771-A0C393ADA246"><p>from an explicit pointer

    32 <li id="GUID-F9C4E446-B390-56AD-8771-A0C393ADA246"><p>from an explicit

    34 into memory and specifying the length of the data and a maximum length.</p> </li>

    33 pointer into memory and specifying the length of the data and a maximum

    35 </ul> <p>The following code fragment constructs a <codeph>TPtr</codeph> to

    34 length.</p> </li>

    36 represent the data already represented by another <codeph>TPtr</codeph>:</p> <codeblock id="GUID-B9296BAB-8B81-52C4-9730-2290C357656A" xml:space="preserve">TPtr ptr1;

    35 </ul> <p>The following code fragment constructs a <codeph>TPtr</codeph> to represent the data already represented by another <codeph>TPtr</codeph>:</p> <codeblock id="GUID-B9296BAB-8B81-52C4-9730-2290C357656A" xml:space="preserve">TPtr ptr1;

    39 ...</codeblock> <p>The following code fragment constructs a <codeph>TPtr</codeph> for

    38 ...</codeblock> <p>The following code fragment constructs a <codeph>TPtr</codeph> for a non-modifiable buffer descriptor, a <codeph>TBufC&lt;TInt&gt;</codeph>, using the <codeph>Des()</codeph> function. Data that would normally

    40 a non-modifiable buffer descriptor, a <codeph>TBufC&lt;TInt&gt;</codeph>, using

    39 be unmodifiable through the <codeph>TBufC&lt;TInt&gt;</codeph> can be

    41 the <codeph>Des()</codeph> function. Data that would normally be unmodifiable

    40 changed through the <codeph>TPtr</codeph>.</p> <p>The source are literals

    42 through the <codeph>TBufC&lt;TInt&gt;</codeph> can be changed through the <codeph>TPtr</codeph>.</p> <p>The

    41 which are converted to descriptor type.</p> <codeblock id="GUID-86F2890B-6AD2-5637-90B6-469554026C12" xml:space="preserve">_LIT(KText,"Hello World!");

    43 source are literals which are converted to descriptor type.</p> <codeblock id="GUID-86F2890B-6AD2-5637-90B6-469554026C12" xml:space="preserve">_LIT(KText,"Hello World!");

    51 ptr.Append(KExtraText);</codeblock> <p>Define a <codeph>TText</codeph> area

    49 ptr.Append(KExtraText);</codeblock> <p>Define a <codeph>TText</codeph> area initialised to contain the string "Have a nice day":</p> <p>The following code fragments show the construction of a <codeph>TPtr</codeph> using a pointer and specifying a length and a maximum length. This

    52 initialised to contain the string "Have a nice day":</p> <p>The following

    50 technique is not commonly used. Literals are a much better way of

    53 code fragments show the construction of a <codeph>TPtr</codeph> using a pointer

    51 defining string constants.</p> <codeblock id="GUID-998F1C38-942B-53F5-BBC5-E33781AF1253" xml:space="preserve">TText str[16] =  {'H', 'a', 'v', 'e', ' ', 'a',

    54 and specifying a length and a maximum length. This technique is not commonly

    55 used. Literals are a much better way of defining string constants.</p> <codeblock id="GUID-998F1C38-942B-53F5-BBC5-E33781AF1253" xml:space="preserve">TText str[16] =  {'H', 'a', 'v', 'e', ' ', 'a',

    57     ' ', 'd', 'a', 'y', '\0'};</codeblock> <codeblock id="GUID-EF4302BB-F536-5B20-B109-1505688B8B60" xml:space="preserve">TPtr ptr(&amp;str[0],15,16);</codeblock> <p>The

    53     ' ', 'd', 'a', 'y', '\0'};</codeblock> <codeblock id="GUID-EF4302BB-F536-5B20-B109-1505688B8B60" xml:space="preserve">TPtr ptr(&amp;str[0],15,16);</codeblock> <p>The descriptor <codeph>ptr</codeph> represents the data in <codeph>str</codeph> and is constructed to have a current length of 15 (the

    58 descriptor <codeph>ptr</codeph> represents the data in <codeph>str</codeph> and

    54 length of the text, excluding the zero terminator) and a maximum length

    59 is constructed to have a current length of 15 (the length of the text, excluding

    55 of 16 (the actual length of <codeph>str</codeph>). Once the descriptor

    60 the zero terminator) and a maximum length of 16 (the actual length of <codeph>str</codeph>).

    56 has been constructed, it has no further use for the zero terminator.</p> <codeblock id="GUID-23A4799F-7B57-5B2B-B549-2BD168D208EC" xml:space="preserve">TPtr ptr(&amp;str[0],15,16);</codeblock> </section>

    61 Once the descriptor has been constructed, it has no further use for the zero

    57 <section id="GUID-AA957AF0-8791-446C-B6E3-DD5EDB642E9E"><title>Replacing

    62 terminator.</p> <codeblock id="GUID-23A4799F-7B57-5B2B-B549-2BD168D208EC" xml:space="preserve">TPtr ptr(&amp;str[0],15,16);</codeblock> </section>

    58 data through the TPtr</title> <p>Data can be completely replaced using

    63 <section id="GUID-AA957AF0-8791-446C-B6E3-DD5EDB642E9E"><title>Replacing data through the TPtr</title> <p>Data can be completely

    59 the assignment operator or the <xref href="GUID-CD3C9BD5-1386-3CF5-A8F6-9BE1AE40689F.dita"><apiname>Copy()</apiname></xref> function.:</p> <codeblock id="GUID-DBF0A411-CA03-5EAD-AFCD-1617C52C195F" xml:space="preserve">_LIT(KText,"Hi there");

    64 replaced using the assignment operator or the <xref href="GUID-CD3C9BD5-1386-3CF5-A8F6-9BE1AE40689F.dita"><apiname>Copy()</apiname></xref> function.:</p> <codeblock id="GUID-DBF0A411-CA03-5EAD-AFCD-1617C52C195F" xml:space="preserve">_LIT(KText,"Hi there");

    68 ptr.Copy(KText);</codeblock> <p>Note the use of the <codeph>_LIT</codeph> macro

    63 ptr.Copy(KText);</codeblock> <p>Note the use of the <codeph>_LIT</codeph> macro to define the source string. A literal is converted into a

    69 to define the source string. A literal is converted into a descriptor type.</p> <p>The

    64 descriptor type.</p> <p>The length of <codeph>ptr</codeph> is now

    70 length of <codeph>ptr</codeph> is now 8 but the maximum length remains unchanged.

    65 8 but the maximum length remains unchanged. The size depends on the

    71 The size depends on the build variant. In a non-Unicode build, this is 8 but

    66 build variant. In a non-Unicode build, this is 8 but in a Unicode

    72 in a Unicode build, this becomes 16 (two bytes for every character).</p> </section>

    67 build, this becomes 16 (two bytes for every character).</p> </section>

    73 <section id="GUID-4A13D438-C058-4370-970E-1139708758E3"><title>Changing the length of data</title> <p>The length of the data

    68 <section id="GUID-4A13D438-C058-4370-970E-1139708758E3"><title>Changing

    74 represented can be changed. </p> <codeblock id="GUID-0AE02AC5-2E85-5950-894A-FF7B6C8C5856" xml:space="preserve">_LIT(KText,"Hi there");

    69 the length of data</title> <p>The length of the data represented can

    70 be changed. </p> <codeblock id="GUID-0AE02AC5-2E85-5950-894A-FF7B6C8C5856" xml:space="preserve">_LIT(KText,"Hi there");

    79 </codeblock> <p>For example, after <codeph>ptr.SetLength(2)</codeph>, the

    75 </codeblock> <p>For example, after <codeph>ptr.SetLength(2)</codeph>, the descriptor represents the string "Hi". The length can even

    80 descriptor represents the string "Hi". The length can even be set to zero

    76 be set to zero so that after <codeph>ptr.Zero()</codeph>, the descriptor

    81 so that after <codeph>ptr.Zero()</codeph>, the descriptor represents no data.

    77 represents no data. Nevertheless, the maximum length remains unchanged.</p> </section>

    82 Nevertheless, the maximum length remains unchanged.</p> </section>

    84 <link>

    79 <link href="GUID-7CB11EAD-260E-551A-85F1-FEAC975FE722.dita"><linktext>Literal

    85 <desc><xref href="GUID-7CB11EAD-260E-551A-85F1-FEAC975FE722.dita">Literal Descriptors</xref></desc>

    80 Descriptors</linktext></link>

    86 </link>