1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>AARM95 - The Package Interfaces.C.Strings</TITLE>
<META NAME="Author" CONTENT="JTC1/SC22/WG9/ARG, by Randall Brukardt, ARG Editor">
<META NAME="GENERATOR" CONTENT="Arm_Form.Exe, Ada Reference Manual generator">
<STYLE type="text/css">
DIV.paranum {position: absolute; font-family: Arial, Helvetica, sans-serif; left: 0.5 em; top: auto}
TT {font-family: "Courier New", monospace}
DT {display: compact}
DIV.Normal {font-family: "Times New Roman", Times, serif; margin-bottom: 0.6em}
DIV.Wide {font-family: "Times New Roman", Times, serif; margin-top: 0.6em; margin-bottom: 0.6em}
DIV.Annotations {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-bottom: 0.6em}
DIV.WideAnnotations {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-top: 0.6em; margin-bottom: 0.6em}
DIV.Index {font-family: "Times New Roman", Times, serif}
DIV.SyntaxSummary {font-family: "Times New Roman", Times, serif; margin-left: 2.0em; margin-bottom: 0.4em}
DIV.Notes {font-family: "Times New Roman", Times, serif; margin-left: 2.0em; margin-bottom: 0.6em}
DIV.NotesHeader {font-family: "Times New Roman", Times, serif; margin-left: 2.0em}
DIV.SyntaxIndented {font-family: "Times New Roman", Times, serif; margin-left: 2.0em; margin-bottom: 0.4em}
DIV.Indented {font-family: "Times New Roman", Times, serif; margin-left: 6.0em; margin-bottom: 0.6em}
DIV.CodeIndented {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-bottom: 0.6em}
DIV.SmallIndented {font-family: "Times New Roman", Times, serif; margin-left: 10.0em; margin-bottom: 0.6em}
DIV.SmallCodeIndented {font-family: "Times New Roman", Times, serif; margin-left: 8.0em; margin-bottom: 0.6em}
DIV.Examples {font-family: "Courier New", monospace; margin-left: 2.0em; margin-bottom: 0.6em}
DIV.SmallExamples {font-family: "Courier New", monospace; font-size: 80%; margin-left: 7.5em; margin-bottom: 0.6em}
DIV.IndentedExamples {font-family: "Courier New", monospace; margin-left: 8.0em; margin-bottom: 0.6em}
DIV.SmallIndentedExamples {font-family: "Courier New", monospace; font-size: 80%; margin-left: 15.0em; margin-bottom: 0.6em}
UL.Bulleted {font-family: "Times New Roman", Times, serif; margin-left: 2.0em; margin-right: 2.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.SmallBulleted {font-family: "Times New Roman", Times, serif; margin-left: 6.0em; margin-right: 6.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.NestedBulleted {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-right: 4.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.SmallNestedBulleted {font-family: "Times New Roman", Times, serif; margin-left: 8.0em; margin-right: 8.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.IndentedBulleted {font-family: "Times New Roman", Times, serif; margin-left: 8.0em; margin-right: 8.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.CodeIndentedBulleted {font-family: "Times New Roman", Times, serif; margin-left: 6.0em; margin-right: 6.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.CodeIndentedNestedBulleted {font-family: "Times New Roman", Times, serif; margin-left: 8.0em; margin-right: 8.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.SyntaxIndentedBulleted {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-right: 4.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.NotesBulleted {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-right: 4.0em; margin-top: 0em; margin-bottom: 0.5em}
UL.NotesNestedBulleted {font-family: "Times New Roman", Times, serif; margin-left: 6.0em; margin-right: 6.0em; margin-top: 0em; margin-bottom: 0.5em}
DL.Hanging {font-family: "Times New Roman", Times, serif; margin-top: 0em; margin-bottom: 0.6em}
DD.Hanging {margin-left: 6.0em}
DL.IndentedHanging {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-top: 0em; margin-bottom: 0.6em}
DD.IndentedHanging {margin-left: 2.0em}
DL.HangingInBulleted {font-family: "Times New Roman", Times, serif; margin-left: 2.0em; margin-right: 2.0em; margin-top: 0em; margin-bottom: 0.5em}
DD.HangingInBulleted {margin-left: 4.0em}
DL.SmallHanging {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-top: 0em; margin-bottom: 0.6em}
DD.SmallHanging {margin-left: 7.5em}
DL.SmallIndentedHanging {font-family: "Times New Roman", Times, serif; margin-left: 8.0em; margin-top: 0em; margin-bottom: 0.6em}
DD.SmallIndentedHanging {margin-left: 2.0em}
DL.SmallHangingInBulleted {font-family: "Times New Roman", Times, serif; margin-left: 6.0em; margin-right: 6.0em; margin-top: 0em; margin-bottom: 0.5em}
DD.SmallHangingInBulleted {margin-left: 5.0em}
DL.Enumerated {font-family: "Times New Roman", Times, serif; margin-right: 0.0em; margin-top: 0em; margin-bottom: 0.5em}
DD.Enumerated {margin-left: 2.0em}
DL.SmallEnumerated {font-family: "Times New Roman", Times, serif; margin-left: 4.0em; margin-right: 4.0em; margin-top: 0em; margin-bottom: 0.5em}
DD.SmallEnumerated {margin-left: 2.5em}
DL.NestedEnumerated {font-family: "Times New Roman", Times, serif; margin-left: 2.0em; margin-right: 2.0em; margin-top: 0em; margin-bottom: 0.5em}
DL.SmallNestedEnumerated {font-family: "Times New Roman", Times, serif; margin-left: 6.0em; margin-right: 6.0em; margin-top: 0em; margin-bottom: 0.5em}
</STYLE>
</HEAD>
<BODY TEXT="#000000" BGCOLOR="#FFFFF0" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">
<P><A HREF="AA-TOC.html">Contents</A> <A HREF="AA-0-29.html">Index</A> <A HREF="AA-B-3.html">Previous</A> <A HREF="AA-B-3-2.html">Next</A></P>
<HR>
<H1> B.3.1 The Package Interfaces.C.Strings</H1>
<DIV Class="Paranum"><FONT SIZE=-2>1</FONT></DIV>
<DIV Class="Normal"> The package Interfaces.C.Strings declares types
and subprograms allowing an Ada program to allocate, reference, update,
and free C-style strings. In particular, the private type chars_ptr corresponds
to a common use of ``char *'' in C programs, and an object of this type
can be passed to a subprogram to which <FONT FACE="Arial, Helvetica">pragma</FONT>
Import(C,...) has been applied, and for which ``char *'' is the type
of the argument of the C function. </DIV>
<H4 ALIGN=CENTER>Static Semantics</H4>
<DIV Class="Paranum"><FONT SIZE=-2>2</FONT></DIV>
<DIV Class="Normal" Style="margin-bottom: 0.4em"> The library package
Interfaces.C.Strings has the following declaration: </DIV>
<DIV Class="Paranum"><FONT SIZE=-2>3</FONT></DIV>
<DIV Class="Examples"><TT><B>package</B> Interfaces.C.Strings <B>is</B><A NAME="I6427"></A><A NAME="I6428"></A><A NAME="I6429"></A><BR>
<B>pragma</B> Preelaborate(Strings);</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>4</FONT></DIV>
<DIV Class="Examples"><TT> <B>type</B> <A NAME="I6430"></A><A NAME="I6431"></A>char_array_access <B>is</B> <B>access</B> <B>all</B> char_array;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>5</FONT></DIV>
<DIV Class="Examples"><TT> <B>type</B> <A NAME="I6432"></A><A NAME="I6433"></A>chars_ptr <B>is</B> <B>private</B>;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>6</FONT></DIV>
<DIV Class="Examples"><TT> <B>type</B> <A NAME="I6434"></A><A NAME="I6435"></A>chars_ptr_array <B>is</B> <B>array</B> (size_t <B>range</B> <>) <B>of</B> chars_ptr;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>7</FONT></DIV>
<DIV Class="Examples"><TT> <A NAME="I6436"></A>Null_Ptr : <B>constant</B> chars_ptr;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>8</FONT></DIV>
<DIV Class="Examples"><TT> <B>function</B> <A NAME="I6437"></A><A NAME="I6438"></A>To_Chars_Ptr (Item : <B>in</B> char_array_access;<BR>
Nul_Check : <B>in</B> Boolean := False)<BR>
<B>return</B> chars_ptr;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>9</FONT></DIV>
<DIV Class="Examples"><TT> <B>function</B> <A NAME="I6439"></A><A NAME="I6440"></A>New_Char_Array (Chars : <B>in</B> char_array) <B>return</B> chars_ptr;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>10</FONT></DIV>
<DIV Class="Examples"><TT> <B>function</B> <A NAME="I6441"></A><A NAME="I6442"></A>New_String (Str : <B>in</B> String) <B>return</B> chars_ptr;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>11</FONT></DIV>
<DIV Class="Examples"><TT> <B>procedure</B> <A NAME="I6443"></A><A NAME="I6444"></A>Free (Item : <B>in</B> <B>out</B> chars_ptr);</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>12</FONT></DIV>
<DIV Class="Examples"><TT> <A NAME="I6445"></A><A NAME="I6446"></A>Dereference_Error : <B>exception</B>;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>13</FONT></DIV>
<DIV Class="Examples"><TT> <B>function</B> <A NAME="I6447"></A><A NAME="I6448"></A>Value (Item : <B>in</B> chars_ptr) <B>return</B> char_array;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>14</FONT></DIV>
<DIV Class="Examples"><TT> <B>function</B> <A NAME="I6449"></A><A NAME="I6450"></A>Value (Item : <B>in</B> chars_ptr; Length : <B>in</B> size_t)<BR>
<B>return</B> char_array;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>15</FONT></DIV>
<DIV Class="Examples"><TT> <B>function</B> <A NAME="I6451"></A><A NAME="I6452"></A>Value (Item : <B>in</B> chars_ptr) <B>return</B> String;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>16</FONT></DIV>
<DIV Class="Examples"><TT> <B>function</B> <A NAME="I6453"></A><A NAME="I6454"></A>Value (Item : <B>in</B> chars_ptr; Length : <B>in</B> size_t)<BR>
<B>return</B> String;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>17</FONT></DIV>
<DIV Class="Examples"><TT> <B>function</B> <A NAME="I6455"></A><A NAME="I6456"></A>Strlen (Item : <B>in</B> chars_ptr) <B>return</B> size_t;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>18</FONT></DIV>
<DIV Class="Examples"><TT> <B>procedure</B> <A NAME="I6457"></A><A NAME="I6458"></A>Update (Item : <B>in</B> chars_ptr;<BR>
Offset : <B>in</B> size_t;<BR>
Chars : <B>in</B> char_array;<BR>
Check : <B>in</B> Boolean := True);</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>19</FONT></DIV>
<DIV Class="Examples"><TT> <B>procedure</B> <A NAME="I6459"></A><A NAME="I6460"></A>Update (Item : <B>in</B> chars_ptr;<BR>
Offset : <B>in</B> size_t;<BR>
Str : <B>in</B> String;<BR>
Check : <B>in</B> Boolean := True);</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>20</FONT></DIV>
<DIV Class="Examples"><TT> <A NAME="I6461"></A><A NAME="I6462"></A>Update_Error : <B>exception</B>;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>21</FONT></DIV>
<DIV Class="Examples"><TT><B>private</B><BR>
... -- <I>not specified by the language</I><BR>
<B>end</B> Interfaces.C.Strings;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>21.a</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>Discussion: </B>The string
manipulation types and subprograms appear in a child of Interfaces.C
versus being there directly, since it is useful to have Interfaces.C
specified as <FONT FACE="Arial, Helvetica">pragma</FONT> Pure.</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>21.b</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1>Differently named functions New_String
and New_Char_Array are declared, since if there were a single overloaded
function a call with a string literal as actual parameter would be ambiguous.
</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>22</FONT></DIV>
<DIV Class="Normal"> The type chars_ptr is C-compatible and corresponds
to the use of C's ``char *'' for a pointer to the first char in a char
array terminated by nul. When an object of type chars_ptr is declared,
its value is by default set to Null_Ptr, unless the object is imported
(see <A HREF="AA-B-1.html">B.1</A>). </DIV>
<DIV Class="Paranum"><FONT SIZE=-2>22.a</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>Discussion: </B>The type char_array_access
is not necessarily C-compatible, since an object of this type may carry
``dope'' information. The programmer should convert from char_array_access
to chars_ptr for objects imported from, exported to, or passed to C.</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>23</FONT></DIV>
<DIV Class="Examples"><TT><B>function</B> To_Chars_Ptr (Item : <B>in</B> char_array_access;<BR>
Nul_Check : <B>in</B> Boolean := False)<BR>
<B>return</B> chars_ptr;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>24/1</FONT></DIV>
<DIV Class="CodeIndented">{<I><A HREF="defect1.html#8652/0061">8652/0061</A></I>}
If Item is <B>null</B>, then To_Chars_Ptr returns Null_Ptr. <U>If Item
is not <B>null</B>,</U><S>Otherwise, if </S>Nul_Check is True<U>,</U>
and Item.<B>all</B> does not contain nul, then the function propagates
Terminator_Error; <U>otherwise</U><S>if Nul_Check is True and Item.<B>all</B>
does contain nul,</S> To_Chars_Ptr performs a pointer conversion with
no allocation of memory.</DIV>
<DIV Class="Paranum"><FONT SIZE=-2>25</FONT></DIV>
<DIV Class="Examples" Style="margin-bottom: 0.9em"><TT><B>function</B> New_Char_Array (Chars : <B>in</B> char_array) <B>return</B> chars_ptr;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>26</FONT></DIV>
<DIV Class="CodeIndented">This function returns a pointer to an allocated
object initialized to Chars(Chars'First .. Index) & nul, where </DIV>
<DIV Class="Paranum"><FONT SIZE=-2>27</FONT></DIV>
<UL Class="CodeIndentedBulleted"><LI TYPE=DISC>Index = Chars'Last if Chars does not contain nul, or</LI></UL>
<DIV Class="Paranum"><FONT SIZE=-2>28</FONT></DIV>
<UL Class="CodeIndentedBulleted"><LI TYPE=DISC>Index is the smallest size_t value I such that Chars(I+1)
= nul. </LI></UL>
<DIV Class="Paranum"><FONT SIZE=-2>28.1</FONT></DIV>
<DIV Class="CodeIndented" Style="margin-bottom: 0.9em"><S></S>Storage_Error
is propagated if the allocation fails.</DIV>
<DIV Class="Paranum"><FONT SIZE=-2>29</FONT></DIV>
<DIV Class="Examples"><TT><B>function</B> New_String (Str : <B>in</B> String) <B>return</B> chars_ptr;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>30</FONT></DIV>
<DIV Class="CodeIndented" Style="margin-bottom: 0.9em">This function
is equivalent to New_Char_Array(To_C(Str)).</DIV>
<DIV Class="Paranum"><FONT SIZE=-2>31</FONT></DIV>
<DIV Class="Examples"><TT><B>procedure</B> Free (Item : <B>in</B> <B>out</B> chars_ptr);</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>32</FONT></DIV>
<DIV Class="CodeIndented" Style="margin-bottom: 0.9em">If Item is Null_Ptr,
then Free has no effect. Otherwise, Free releases the storage occupied
by Value(Item), and resets Item to Null_Ptr.</DIV>
<DIV Class="Paranum"><FONT SIZE=-2>33</FONT></DIV>
<DIV Class="Examples"><TT><B>function</B> Value (Item : <B>in</B> chars_ptr) <B>return</B> char_array;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>34</FONT></DIV>
<DIV Class="CodeIndented" Style="margin-bottom: 0.9em">If Item = Null_Ptr
then Value propagates Dereference_Error. Otherwise Value returns the
prefix of the array of chars pointed to by Item, up to and including
the first nul. The lower bound of the result is 0. If Item does not point
to a nul-terminated string, then execution of Value is erroneous.</DIV>
<DIV Class="Paranum"><FONT SIZE=-2>35</FONT></DIV>
<DIV Class="Examples"><TT><B>function</B> Value (Item : <B>in</B> chars_ptr; Length : <B>in</B> size_t)<BR>
<B>return</B> char_array;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>36/1</FONT></DIV>
<DIV Class="CodeIndented">{<I><A HREF="defect1.html#8652/0062">8652/0062</A></I>}
If Item = Null_Ptr then Value<S>(Item)</S> propagates Dereference_Error.
Otherwise Value returns the shorter of two arrays<U>, either</U><S>:</S>
the first Length chars pointed to by Item, <U>or</U><S>and</S> Value(Item).
The lower bound of the result is 0. <U>If Length is 0, then Value propagates
Constraint_Error.</U> </DIV>
<DIV Class="Paranum"><FONT SIZE=-2>36.a</FONT></DIV>
<DIV Class="Annotations" Style="margin-bottom: 0.9em"><FONT SIZE=-1><B>Ramification:
</B>Value(New_Char_Array(Chars)) = Chars if Chars does not contain nul;
else Value(New_Char_Array( Chars)) is the prefix of Chars up to and including
the first nul. </FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>37</FONT></DIV>
<DIV Class="Examples"><TT><B>function</B> Value (Item : <B>in</B> chars_ptr) <B>return</B> String;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>38</FONT></DIV>
<DIV Class="CodeIndented" Style="margin-bottom: 0.9em">Equivalent to
To_Ada(Value(Item), Trim_Nul=>True).</DIV>
<DIV Class="Paranum"><FONT SIZE=-2>39</FONT></DIV>
<DIV Class="Examples"><TT><B>function</B> Value (Item : <B>in</B> chars_ptr; Length : <B>in</B> size_t)<BR>
<B>return</B> String;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>40/1</FONT></DIV>
<DIV Class="CodeIndented">{<I><A HREF="defect1.html#8652/0063">8652/0063</A></I>}
Equivalent to To_Ada(Value(Item, Length)<U> & nul</U>, Trim_Nul=>True).</DIV>
<DIV Class="Paranum"><FONT SIZE=-2>41</FONT></DIV>
<DIV Class="Examples" Style="margin-bottom: 0.9em"><TT><B>function</B> Strlen (Item : <B>in</B> chars_ptr) <B>return</B> size_t;</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>42</FONT></DIV>
<DIV Class="CodeIndented" Style="margin-bottom: 0.9em">Returns <I>Val</I>'Length-1
where <I>Val</I> = Value(Item); propagates Dereference_Error if Item
= Null_Ptr. </DIV>
<DIV Class="Paranum"><FONT SIZE=-2>42.a</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>Ramification: </B>Strlen returns
the number of chars in the array pointed to by Item, up to and including
the char immediately before the first nul.</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>42.b</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1>Strlen has the same possibility
for erroneous execution as Value, in cases where the string has not been
nul-terminated.</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>42.c</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1>Strlen has the effect of C's strlen
function. </FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>43</FONT></DIV>
<DIV Class="Examples"><TT><B>procedure</B> Update (Item : <B>in</B> chars_ptr;<BR>
Offset : <B>in</B> size_t;<BR>
Chars : <B>in</B> char_array;<BR>
Check : Boolean := True);</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>44/1</FONT></DIV>
<DIV Class="CodeIndented">{<I><A HREF="defect1.html#8652/0064">8652/0064</A></I>}
<U>If Item = Null_Ptr, then Update propagates Dereference_Error. Otherwise,
t</U><S>T</S>his procedure updates the value pointed to by Item, starting
at position Offset, using Chars as the data to be copied into the array.
Overwriting the nul terminator, and skipping with the Offset past the
nul terminator, are both prevented if Check is True, as follows: </DIV>
<DIV Class="Paranum"><FONT SIZE=-2>45</FONT></DIV>
<UL Class="CodeIndentedBulleted" Style="margin-bottom: 0.3em"><LI TYPE=DISC>Let N = Strlen(Item). If Check is True, then: </LI></UL>
<DIV Class="Paranum"><FONT SIZE=-2>46</FONT></DIV>
<UL Class="CodeIndentedNestedBulleted"><LI TYPE=DISC>If Offset+Chars'Length>N, propagate Update_Error.</LI></UL>
<DIV Class="Paranum"><FONT SIZE=-2>47</FONT></DIV>
<UL Class="CodeIndentedNestedBulleted"><LI TYPE=DISC>Otherwise, overwrite the data in the array pointed to by
Item, starting at the char at position Offset, with the data in Chars.
</LI></UL>
<DIV Class="Paranum"><FONT SIZE=-2>48</FONT></DIV>
<UL Class="CodeIndentedBulleted" Style="margin-bottom: 0.7em"><LI TYPE=DISC>If Check is False, then processing is as above, but with
no check that Offset+Chars'Length>N. </LI></UL>
<DIV Class="Paranum"><FONT SIZE=-2>48.a</FONT></DIV>
<DIV Class="Annotations"><FONT SIZE=-1><B>Ramification: </B>If Chars
contains nul, Update's effect may be to ``shorten'' the pointed-to char
array.</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>49</FONT></DIV>
<DIV Class="Examples"><TT><B>procedure</B> Update (Item : <B>in</B> chars_ptr;<BR>
Offset : <B>in</B> size_t;<BR>
Str : <B>in</B> String;<BR>
Check : <B>in</B> Boolean := True);</TT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>50</FONT></DIV>
<DIV Class="CodeIndented">Equivalent to Update(Item, Offset, To_C(Str),
Check). </DIV>
<H4 ALIGN=CENTER>Erroneous Execution</H4>
<DIV Class="Paranum"><FONT SIZE=-2>51</FONT></DIV>
<DIV Class="Normal"> <A NAME="I6463"></A>Execution of any of the following
is erroneous if the Item parameter is not null_ptr and Item does not
point to a nul-terminated array of chars. </DIV>
<DIV Class="Paranum"><FONT SIZE=-2>52</FONT></DIV>
<UL Class="Bulleted"><LI TYPE=DISC>a Value function not taking a Length parameter,</LI></UL>
<DIV Class="Paranum"><FONT SIZE=-2>53</FONT></DIV>
<UL Class="Bulleted"><LI TYPE=DISC>the Free procedure,</LI></UL>
<DIV Class="Paranum"><FONT SIZE=-2>54</FONT></DIV>
<UL Class="Bulleted"><LI TYPE=DISC>the Strlen function. </LI></UL>
<DIV Class="Paranum"><FONT SIZE=-2>55</FONT></DIV>
<DIV Class="Normal"> <A NAME="I6464"></A>Execution of Free(X) is also
erroneous if the chars_ptr X was not returned by New_Char_Array or New_String.</DIV>
<DIV Class="Paranum"><FONT SIZE=-2>56</FONT></DIV>
<DIV Class="Normal"> <A NAME="I6465"></A>Reading or updating a freed
char_array is erroneous.</DIV>
<DIV Class="Paranum"><FONT SIZE=-2>57</FONT></DIV>
<DIV Class="Normal"> <A NAME="I6466"></A>Execution of Update is erroneous
if Check is False and a call with Check equal to True would have propagated
Update_Error. </DIV>
<DIV Class="NotesHeader"><FONT SIZE=-1>NOTES</FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>58</FONT></DIV>
<DIV Class="Notes"><FONT SIZE=-1>13 New_Char_Array and New_String
might be implemented either through the allocation function from the
C environment (``malloc'') or through Ada dynamic memory allocation (``new'').
The key points are </FONT></DIV>
<DIV Class="Paranum"><FONT SIZE=-2>59</FONT></DIV>
<UL Class="NotesBulleted"><FONT SIZE=-1><LI TYPE=DISC>the returned value (a chars_ptr) is represented as a C
``char *'' so that it may be passed to C functions;</LI></FONT></UL>
<DIV Class="Paranum"><FONT SIZE=-2>60</FONT></DIV>
<UL Class="NotesBulleted"><FONT SIZE=-1><LI TYPE=DISC>the allocated object should be freed by the programmer
via a call of Free, not by a called C function. </LI></FONT></UL>
<HR>
<P><A HREF="AA-TOC.html">Contents</A> <A HREF="AA-0-29.html">Index</A> <A HREF="AA-B-3.html">Previous</A> <A HREF="AA-B-3-2.html">Next</A> <A HREF="AA-TTL.html">Legal</A></P>
</BODY>
</HTML>
|
