diff options
Diffstat (limited to 'apps/codecs/dumb/docs/ptr.txt')
-rw-r--r-- | apps/codecs/dumb/docs/ptr.txt | 129 |
1 files changed, 129 insertions, 0 deletions
diff --git a/apps/codecs/dumb/docs/ptr.txt b/apps/codecs/dumb/docs/ptr.txt new file mode 100644 index 0000000000..0eb42ccf02 --- /dev/null +++ b/apps/codecs/dumb/docs/ptr.txt | |||
@@ -0,0 +1,129 @@ | |||
1 | /* _______ ____ __ ___ ___ | ||
2 | * \ _ \ \ / \ / \ \ / / ' ' ' | ||
3 | * | | \ \ | | || | \/ | . . | ||
4 | * | | | | | | || ||\ /| | | ||
5 | * | | | | | | || || \/ | | ' ' ' | ||
6 | * | | | | | | || || | | . . | ||
7 | * | |_/ / \ \__// || | | | ||
8 | * /_______/ynamic \____/niversal /__\ /____\usic /| . . ibliotheque | ||
9 | * / \ | ||
10 | * / . \ | ||
11 | * ptr.txt - Pointer explanation. / / \ \ | ||
12 | * | < / \_ | ||
13 | * | \/ /\ / | ||
14 | * \_ / > / | ||
15 | * | \ / / | ||
16 | * | ' / | ||
17 | * \__/ | ||
18 | */ | ||
19 | |||
20 | |||
21 | A pointer is a small variable (often the same size as an int BUT NOT ALWAYS) | ||
22 | that holds the address of something in memory. You create a pointer by adding | ||
23 | a * to a variable, as follows: | ||
24 | |||
25 | int x, *y; | ||
26 | |||
27 | x = 5; | ||
28 | y = &x; | ||
29 | |||
30 | The & means 'address of', so &x gives us a pointer to x. We are storing it in | ||
31 | y. | ||
32 | |||
33 | (*y)++; | ||
34 | |||
35 | The * here means 'value at'. It's known as the 'dereferencing' operator. When | ||
36 | written before a pointer, as it is here, it allows you to treat the value | ||
37 | like a normal variable. In this case we are incrementing the value. If we | ||
38 | look at x, we'll find that it now contains 6, not 5. | ||
39 | |||
40 | y++; | ||
41 | |||
42 | Here we are incrementing the pointer itself. This is useful for traversing | ||
43 | through an array, but in this particular example it is not much use. | ||
44 | |||
45 | *y++; | ||
46 | |||
47 | Beware; this will increment the pointer, not the value stored there. It will | ||
48 | return the value stored at the pointer (before incrementing the pointer), so | ||
49 | you can use this in a bigger expression. This is why we needed brackets in | ||
50 | the first example. | ||
51 | |||
52 | Note that you will not need these three examples when working with DUMB; they | ||
53 | are simply to help illustrate the idea of pointers. | ||
54 | |||
55 | Also be aware that when defining pointers you attach the * to the variable, | ||
56 | not to the type. The following example will create a pointer and an int, not | ||
57 | two pointers: | ||
58 | |||
59 | int *a, b; | ||
60 | |||
61 | That is why I believe it's a good idea to put a space before the * and not | ||
62 | after it, although programmers are divided on this. | ||
63 | |||
64 | y = 0; | ||
65 | y = NULL; | ||
66 | |||
67 | These two statements are equivalent. 0, or NULL, is a special value that is | ||
68 | guaranteed to have a different value from any valid pointer. This is most | ||
69 | often used to indicate that something doesn't point anywhere. DUMB's | ||
70 | functions may return it on occasion. However, in simple usage of DUMB, you | ||
71 | will not actually need to check for it. | ||
72 | |||
73 | Some of DUMB's functions return pointers to structs. (A struct is an | ||
74 | aggregration of other variables, such as ints, pointers, or other structs. | ||
75 | You can generally treat a struct as a single unit.) Here's an example of such | ||
76 | a function: | ||
77 | |||
78 | DUH *dumb_load_it(const char *filename); | ||
79 | |||
80 | You do not know what the DUH struct actually contains; dumb.h and aldumb.h | ||
81 | only give the compiler enough information to deal with pointers to them. DUMB | ||
82 | will take charge of everything that happens inside a DUH struct. | ||
83 | |||
84 | The above function will create a DUH struct for you. First it allocates | ||
85 | the memory it needs, then it fills the struct with data, then it returns a | ||
86 | pointer. This DUH struct will contain the data necessary to play an IT file. | ||
87 | You can define a suitable variable and store the pointer in it as follows: | ||
88 | |||
89 | DUH *duh = dumb_load_it("music.it"); | ||
90 | |||
91 | Or this can be split up: | ||
92 | |||
93 | DUH *duh; | ||
94 | duh = dumb_load_it("music.it"); | ||
95 | |||
96 | In order to use this DUH struct later, you must pass its pointer to other | ||
97 | functions. To pass the pointer to a function, simply write 'duh' for the | ||
98 | appropriate parameter. | ||
99 | |||
100 | When you've finished with a DUH struct (this applies equally to the other | ||
101 | structs DUMB deals with), you must pass it to an appropriate function for | ||
102 | freeing up the memory: | ||
103 | |||
104 | unload_duh(duh); | ||
105 | |||
106 | After you've done this, the memory will no longer be allocated, and the | ||
107 | pointer will have no meaning. You may wish to set it to NULL at this point | ||
108 | for safety. Alternatively just be sure not to use the present value of the | ||
109 | pointer any more. You can of course assign a new value to the pointer, e.g. | ||
110 | by calling dumb_load_it() again. | ||
111 | |||
112 | Note the following: | ||
113 | |||
114 | DUH *duh2 = duh; | ||
115 | |||
116 | This only duplicates the pointer, not the DUH itself. You still only have one | ||
117 | copy of the DUH. There is no way of duplicating a DUH, short of loading it | ||
118 | twice. This is not a problem, because DUMB can play it 'twice at the same | ||
119 | time' anyway. | ||
120 | |||
121 | That should be all you need to know about pointers in order to use DUMB. If | ||
122 | there's anything you feel should be explained better here, or anything else | ||
123 | that should be added, please don't hesitate to let me know! | ||
124 | |||
125 | |||
126 | Ben Davis | ||
127 | entheh@users.sf.net | ||
128 | IRC EFnet #dumb | ||
129 | See readme.txt for details on using IRC. | ||