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
|
<!DOCTYPE html>
<html>
<head>
<title>MuPDF Coding Style</title>
<link rel="stylesheet" href="style.css" type="text/css">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
<header>
<h1>MuPDF Coding Style</h1>
</header>
<nav>
<a href="http://mupdf.com/index.html">ABOUT</a>
<a href="http://mupdf.com/news.html">NEWS</a>
<a href="index.html">DOCUMENTATION</a>
<a href="http://mupdf.com/downloads/">DOWNLOAD</a>
<a href="http://git.ghostscript.com/?p=mupdf.git;a=summary">SOURCE</a>
<a href="https://bugs.ghostscript.com/">BUGS</a>
</nav>
<article>
<h2>Names</h2>
<p>
Functions should be named according to one of the following schemes:
<ul>
<li> verb_noun
<li> verb_noun_with_noun
<li> noun_attribute
<li> set_noun_attribute
<li> noun_from_noun -- convert from one type to another (avoid noun_to_noun)
</ul>
<p>
Prefixes are mandatory for exported functions, macros, enums, globals and types.
<ul>
<li> fz for common code
<li> pdf, xps, etc., for interpreter specific code
</ul>
<p>
Prefixes are optional (but encouraged) for private functions and types.
<p>
Avoid using 'get' as this is a meaningless and redundant filler word.
<p>
These words are reserved for reference counting schemes:
<ul>
<li> new, find, load, open, keep -- return objects that you are responsible for freeing.
<li> drop -- relinquish ownership of the object passed in.
</ul>
<p>
When searching for an object or value, the name used depends on whether
returning the value is passing ownership:
<ul>
<li> lookup -- return a value or borrowed pointer
<li> find -- return an object that the caller is responsible for freeing
</ul>
<h2>Types</h2>
<p>
Various different integer types are used throughout MuPDF.
<p>
In general:
<ul>
<li> int is assumed to be 32bit at least.
<li> short is assumed to be exactly 16 bits.
<li> char is assumed to be exactly 8 bits.
<li> array sizes, string lengths, and allocations are measured using size_t.
size_t is 32bit in 32bit builds, and 64bit on all 64bit builds.
<li> buffers of data use unsigned chars (or uint8_t).
<li> Offsets within files/streams are represented using fz_off_t.
fz_off_t is 64bits in 64bit builds, or in 32bit builds with FZ_LARGEFILE defined.
Otherwise it is a native int (so 32bit in 32bit builds).
</ul>
<p>
In addition, we use floats (and avoid doubles when possible), assumed to be IEEE compliant.
<h2>Reference counting</h2>
<p>
Reference counting uses special words in functions to make it easy to remember
and follow the rules.
<p>
Words that take ownership: new, find, load, open, keep.
<p>
Words that release ownership: drop.
<p>
If an object is returned by a function with one of the special words that take
ownership, you are responsible for freeing it by calling "drop" or "free", or
"close" before you return. You may pass ownership of an owned object by return
it only if you name the function using one of the special words.
<p>
Any objects returned by functions that do not have any of these special words,
are borrowed and have a limited life time. Do not hold on to them past the
duration of the current function, or stow them away inside structs. If you need
to keep the object for longer than that, you have to either "keep" it or make
your own copy.
</article>
<footer>
<a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a>
Copyright © 2006-2017 Artifex Software Inc.
</footer>
</body>
</html>
|
