[mascara-docs.git] / lang / C / the.ansi.c.programming.language / c.programming.notes.int / sx5.html
| blob | 7c65cf361603d646652f6c7ec9a9eea5903258c6 |
2 <!-- This collection of hypertext pages is Copyright 1995-7 by Steve Summit. -->
3 <!-- This material may be freely redistributed and used -->
4 <!-- but may not be republished or sold without permission. -->
5 <html>
6 <head>
13 </head>
14 <body>
17 <p>Arrays are ``second-class citizens'' in C.
18 Related to the fact that arrays can't be assigned
19 is the fact that
20 they can't be returned by functions, either;
21 that is,
22 there is no such type as ``function returning array of ...''.
23 In this chapter we'll study three workarounds,
24 three ways to implement a function
25 which attempts to return a string
27 or an array of some other type.
28 </p><p>In the last chapter, we looked at some code for converting an integer
29 into a string of digits representing its value.
30 This operation is the inverse of the function performed
32 Suppose we wanted to wrap our digit-generating code
34 How would it return the generated string of digits?
35 We'll use this example to demonstrate all three techniques.
36 For simplicity, though,
38 in each example function;
41 most C programs call it directly when they need to
42 convert integers to strings,
45 so that we can set it aside and make sure we never use it.
47 <pre>
48 char *itoa(int n)
49 {
50 char retbuf[25];
51 sprintf(retbuf, "%d", n);
52 return retbuf;
53 }
54 </pre>
55 This looks superficially reasonable,
56 and it might well be what we'd write at first if we weren't
57 being careful.
58 (It might even seem to work, at first.)
59 However, it has a serious, fatal flaw:
61 Since it's a regular local variable,
63 which means that it springs into existence when the function is called
65 Therefore,
67 is to an array which no longer exists by the time the caller
68 receives the pointer.
71 by the ``equivalence of arrays and pointers,''
74 When the caller tries to use the pointer,
75 the string
76 created
78 or the memory might have been re-used by some other function.
81 Functions must never return pointers to local,
82 automatic-duration arrays.
83 </p><p>Since the problem with returning a pointer to a local array
84 is that the array has automatic duration by default,
86 and the first of our three working methods of returning arrays from functions,
88 <pre>
89 char *itoa(int n)
90 {
91 static char retbuf[25];
92 sprintf(retbuf, "%d", n);
93 return retbuf;
94 }
95 </pre>
97 returns, so the pointer is still valid by the time the caller uses it.
99 is a practical and popular solution
100 to the problem of ``returning'' an array,
101 but it has one drawback.
102 Each time you call the function,
103 it re-uses the same array and returns the same pointer.
104 Therefore,
105 when you call the function a second time,
106 whatever information it ``returned'' to you last time
107 will be overwritten.
108 (More precisely, the information,
109 that the function returned a pointer to,
110 will be overwritten.)
111 For example,
112 suppose we had occasion
114 with the intention of using it later,
116 <pre>
117 int i = 23;
118 char *p1, *p2;
119 p1 = itoa(i);
120 i = i + 10;
121 p2 = itoa(i);
122 printf("old i = %s, new i = %s\n", p1, p2);
123 </pre>
124 But this won't work as we
125 expect--the
128 static
130 which was stored by the first call.
132 the last line will print the new value, twice.
136 the same pointer to that same array.
137 </p><p>We can see the same problem in an even simpler example.
138 Suppose we had never heard of
140 We might try to call something like this:
141 <pre>
142 printf("i = %s, j = %s\n", itoa(i), itoa(j));
143 </pre>
146 What will happen?
147 Either the compiler will make
149 or the second.
150 (It turns out that it's not specified
151 which order the compiler will use;
152 different compilers behave differently in this respect.)
154 will be the one that
155 gets to keep its return value in
159 but it won't be able to print two distinct values.
160 </p><p>The moral is that
162 the caller has to be a little bit careful,
163 and must never expect the return pointer from one call to the function
164 to be usable after a later call to the function.
165 Sometimes this restriction is a real problem;
166 other times it's perfectly acceptable.
167 (Some of the functions in the standard C library use this technique;
169 which converts timestamp values to printable strings.
170 When you see a cryptic sentence like
171 ``The returned pointer is to static data
172 which is overwritten with each call''
173 in the documentation for a library function,
174 it means that the function is using this technique.)
176 we should use one of the other two techniques, described next.
178 to hold the return value,
180 and use that.
181 In this case,
182 the function accepts
183 at least one additional argument
184 (in addition to any data to be operated on):
185 a pointer to the location to write the result back to.
188 along these lines,
189 it might look like this:
190 <pre>
191 char *itoa(int n, char buf[])
192 {
193 sprintf(buf, "%d", n);
194 return buf;
195 }
196 </pre>
199 <pre>
200 int i = 23;
201 char buf[25];
202 char *str = itoa(i, buf);
203 </pre>
204 There are two differences between this
206 (Well, three, really;
207 of course
208 the two functions do totally different things.)
209 One difference is that
214 which is a deficiency.
215 If the caller ever passes an array
216 which is too small to hold all the digits of the converted integer,
218 will sail off the end of the array
219 and scribble on some other part of memory.
220 (Needless to say, this can be a disaster.)
221 </p><p>Another difference is that the return value
223 isn't terribly useful.
225 is always the same as the pointer you handed it.
227 as its formal return value,
228 you could still get your hands on the string it created,
229 since it would be sitting right there in your own array
230 (the one that you passed
231 to
234 we had a second thing to return as the formal return value,
235 namely the length of the line we'd just read.
236 </p><p>However, this second strategy is also popular and workable.
239 both use this technique.
240 </p><p>When the limit of a single static return array within the function
241 would be unacceptable,
242 and when it would be a nuisance for the caller
243 to have to declare or otherwise allocate return arrays,
244 a third option
245 is for the function to dynamically allocate some memory
246 for the returned array
249 demonstrating this technique:
250 <pre>
251 char *itoa(int n)
252 {
253 char *retbuf = malloc(25);
254 if(retbuf == NULL)
255 return NULL;
256 sprintf(retbuf, "%d", n);
257 return retbuf;
258 }
259 </pre>
260 Now the caller can go back to saying simple things like
261 <pre>
262 char *p = itoa(i);
263 </pre>
264 and it no longer has to worry about the possibility that
266 will overwrite the results of the first.
270 The caller should really be checking for this null pointer return
272 before using the pointer.
274 we'll have allocated
276 or a quarter of a meg.
278 to deallocate all of that memory,
279 it will be wasted.
280 Few programs can afford to waste that much memory.
281 (Once upon a time,
282 few programs could get that much memory, period.)
283 The ``someone''
286 it has no idea when the caller is done
289 So it will be the caller's responsibility
291 and to free it when it's no longer needed,
292 or else memory will gradually leak away.
293 </OL>We can work around the first problem--if
294 we expect that there will usually be enough memory,
296 and if all the caller would do in an out-of-memory situation is
297 print an error message and abort,
298 we can move the test down into the function:
299 <pre>
300 char *retbuf = malloc(25);
301 if(retbuf == NULL)
302 {
303 fprintf(stderr, "out of memory\n");
304 exit(EXIT_FAILURE);
305 }
306 </pre>
307 Now the function never returns a null pointer,
308 so the caller doesn't have to check.
310 </p><p></p><p>In summary, we've seen three ways
311 of ``returning'' arrays from functions,
312 none of which is perfect.
314 but only for functions
315 which it's unlikely that the caller will be trying to call multiple times
316 and retain multiple return values.
318 in that it violates the notion
319 that calling code shouldn't need to know
320 about the inner, implementation details of a called function.)
321 The caller-passes-an-array technique
322 is useful when the caller might have a number of calls to the function active,
323 but when that number is small and fixed,
324 so that the caller can easily declare and keep track
325 of a number of return arrays
326 (if necessary).
327 Finally,
328 when there might be an arbitrary number of calls to the function,
329 or when maximum flexibility is otherwise needed,
331 but with its extra flexibility comes some costs,
332 the most important of which is that the caller must remember to
333 free the returned pointers.
334 </p><hr>
335 <p>
336 Read sequentially:
341 </p>
342 <p>
346 </p>
347 </body>
348 </html>