/work/workdir/UnpackedTarball/cairo/src/cairo-version.c

Source
/* -*- Mode: c; c-basic-offset: 4; indent-tabs-mode: t; tab-width: 8; -*- */
/* cairo - a vector graphics library with display and print output
 *
 * Copyright © 2002 University of Southern California
 * Copyright © 2005 Red Hat, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it either under the terms of the GNU Lesser General Public
 * License version 2.1 as published by the Free Software Foundation
 * (the "LGPL") or, at your option, under the terms of the Mozilla
 * Public License Version 1.1 (the "MPL"). If you do not alter this
 * notice, a recipient may use your version of this file under either
 * the MPL or the LGPL.
 *
 * You should have received a copy of the LGPL along with this library
 * in the file COPYING-LGPL-2.1; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Suite 500, Boston, MA 02110-1335, USA
 * You should have received a copy of the MPL along with this library
 * in the file COPYING-MPL-1.1
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.1 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY
 * OF ANY KIND, either express or implied. See the LGPL or the MPL for
 * the specific language governing rights and limitations.
 *
 * The Original Code is the cairo graphics library.
 *
 * The Initial Developer of the Original Code is University of Southern
 * California.
 *
 * Contributor(s):
 *  Carl D. Worth <cworth@cworth.org>
 */

#include "cairoint.h"

/**
 * SECTION:cairo-version
 * @Title: Version Information
 * @Short_Description: Compile-time and run-time version checks.
 *
 * Cairo has a three-part version number scheme. In this scheme, we use
 * even vs. odd numbers to distinguish fixed points in the software
 * vs. in-progress development, (such as from git instead of a tar file,
 * or as a "snapshot" tar file as opposed to a "release" tar file).
 *
 * <informalexample><screen>
 *  _____ Major. Always 1, until we invent a new scheme.
 * /  ___ Minor. Even/Odd = Release/Snapshot (tar files) or Branch/Head (git)
 * | /  _ Micro. Even/Odd = Tar-file/git
 * | | /
 * 1.0.0
 * </screen></informalexample>
 *
 * Here are a few examples of versions that one might see.
 * <informalexample><screen>
 * Releases
 * --------
 * 1.0.0 - A major release
 * 1.0.2 - A subsequent maintenance release
 * 1.2.0 - Another major release
 * &nbsp;
 * Snapshots
 * ---------
 * 1.1.2 - A snapshot (working toward the 1.2.0 release)
 * &nbsp;
 * In-progress development (eg. from git)
 * --------------------------------------
 * 1.0.1 - Development on a maintenance branch (toward 1.0.2 release)
 * 1.1.1 - Development on head (toward 1.1.2 snapshot and 1.2.0 release)
 * </screen></informalexample>
 *
 * <refsect2>
 * <title>Compatibility</title>
 *
 * The API/ABI compatibility guarantees for various versions are as
 * follows. First, let's assume some cairo-using application code that is
 * successfully using the API/ABI "from" one version of cairo. Then let's
 * ask the question whether this same code can be moved "to" the API/ABI
 * of another version of cairo.
 *
 * Moving from a release to any later version (release, snapshot,
 * development) is always guaranteed to provide compatibility.
 *
 * Moving from a snapshot to any later version is not guaranteed to
 * provide compatibility, since snapshots may introduce new API that ends
 * up being removed before the next release.
 *
 * Moving from an in-development version (odd micro component) to any
 * later version is not guaranteed to provide compatibility. In fact,
 * there's not even a guarantee that the code will even continue to work
 * with the same in-development version number. This is because these
 * numbers don't correspond to any fixed state of the software, but
 * rather the many states between snapshots and releases.
 *
 * </refsect2>
 * <refsect2>
 * <title>Examining the version</title>
 *
 * Cairo provides the ability to examine the version at either
 * compile-time or run-time and in both a human-readable form as well as
 * an encoded form suitable for direct comparison. Cairo also provides the
 * macro CAIRO_VERSION_ENCODE() to perform the encoding.
 *
 * <informalexample><screen>
 * Compile-time
 * ------------
 * #CAIRO_VERSION_STRING   Human-readable
 * #CAIRO_VERSION          Encoded, suitable for comparison
 * &nbsp;
 * Run-time
 * --------
 * cairo_version_string()  Human-readable
 * cairo_version()         Encoded, suitable for comparison
 * </screen></informalexample>
 *
 * For example, checking that the cairo version is greater than or equal
 * to 1.0.0 could be achieved at compile-time or run-time as follows:
 *
 * <informalexample><programlisting>
 * ##if CAIRO_VERSION >= CAIRO_VERSION_ENCODE(1, 0, 0)
 * printf ("Compiling with suitable cairo version: %s\n", %CAIRO_VERSION_STRING);
 * ##endif
 *
 * if (cairo_version() >= CAIRO_VERSION_ENCODE(1, 0, 0))
 *     printf ("Running with suitable cairo version: %s\n", cairo_version_string ());
 * </programlisting></informalexample>
 *
 * </refsect2>
 *
 **/

/**
 * CAIRO_VERSION:
 *
 * The version of cairo available at compile-time, encoded using
 * CAIRO_VERSION_ENCODE().
 *
 * Since: 1.0
 **/

/**
 * CAIRO_VERSION_MAJOR:
 *
 * The major component of the version of cairo available at compile-time.
 *
 * Since: 1.0
 **/

/**
 * CAIRO_VERSION_MINOR:
 *
 * The minor component of the version of cairo available at compile-time.
 *
 * Since: 1.0
 **/

/**
 * CAIRO_VERSION_MICRO:
 *
 * The micro component of the version of cairo available at compile-time.
 *
 * Since: 1.0
 **/

/**
 * CAIRO_VERSION_STRING:
 *
 * A human-readable string literal containing the version of cairo available
 * at compile-time, in the form of "X.Y.Z".
 *
 * Since: 1.8
 **/

/**
 * CAIRO_VERSION_ENCODE:
 * @major: the major component of the version number
 * @minor: the minor component of the version number
 * @micro: the micro component of the version number
 *
 * This macro encodes the given cairo version into an integer.  The numbers
 * returned by %CAIRO_VERSION and cairo_version() are encoded using this macro.
 * Two encoded version numbers can be compared as integers.  The encoding ensures
 * that later versions compare greater than earlier versions.
 *
 * Returns: the encoded version.
 *
 * Since: 1.0
 **/

/**
 * CAIRO_VERSION_STRINGIZE:
 * @major: the major component of the version number
 * @minor: the minor component of the version number
 * @micro: the micro component of the version number
 *
 * This macro encodes the given cairo version into an string.  The numbers
 * returned by %CAIRO_VERSION_STRING and cairo_version_string() are encoded using this macro.
 * The parameters to this macro must expand to numerical literals.
 *
 * Returns: a string literal containing the version.
 *
 * Since: 1.8
 **/

/**
 * cairo_version:
 *
 * Returns the version of the cairo library encoded in a single
 * integer as per %CAIRO_VERSION_ENCODE. The encoding ensures that
 * later versions compare greater than earlier versions.
 *
 * A run-time comparison to check that cairo's version is greater than
 * or equal to version X.Y.Z could be performed as follows:
 *
 * <informalexample><programlisting>
 * if (cairo_version() >= CAIRO_VERSION_ENCODE(X,Y,Z)) {...}
 * </programlisting></informalexample>
 *
 * See also cairo_version_string() as well as the compile-time
 * equivalents %CAIRO_VERSION and %CAIRO_VERSION_STRING.
 *
 * Return value: the encoded version.
 *
 * Since: 1.0
 **/
int
cairo_version (void)
{
    return CAIRO_VERSION;
}

/**
 * cairo_version_string:
 *
 * Returns the version of the cairo library as a human-readable string
 * of the form "X.Y.Z".
 *
 * See also cairo_version() as well as the compile-time equivalents
 * %CAIRO_VERSION_STRING and %CAIRO_VERSION.
 *
 * Return value: a string containing the version.
 *
 * Since: 1.0
 **/
const char*
cairo_version_string (void)
{
    return CAIRO_VERSION_STRING;
}
slim_hidden_def (cairo_version_string);

Coverage Report

Created: 2025-07-07 10:01

Line	Count	Source
1		/* -- Mode: c; c-basic-offset: 4; indent-tabs-mode: t; tab-width: 8; -- */
2		/* cairo - a vector graphics library with display and print output
3		*
4		* Copyright © 2002 University of Southern California
5		* Copyright © 2005 Red Hat, Inc.
6		*
7		* This library is free software; you can redistribute it and/or
8		* modify it either under the terms of the GNU Lesser General Public
9		* License version 2.1 as published by the Free Software Foundation
10		* (the "LGPL") or, at your option, under the terms of the Mozilla
11		* Public License Version 1.1 (the "MPL"). If you do not alter this
12		* notice, a recipient may use your version of this file under either
13		* the MPL or the LGPL.
14		*
15		* You should have received a copy of the LGPL along with this library
16		* in the file COPYING-LGPL-2.1; if not, write to the Free Software
17		* Foundation, Inc., 51 Franklin Street, Suite 500, Boston, MA 02110-1335, USA
18		* You should have received a copy of the MPL along with this library
19		* in the file COPYING-MPL-1.1
20		*
21		* The contents of this file are subject to the Mozilla Public License
22		* Version 1.1 (the "License"); you may not use this file except in
23		* compliance with the License. You may obtain a copy of the License at
24		* http://www.mozilla.org/MPL/
25		*
26		* This software is distributed on an "AS IS" basis, WITHOUT WARRANTY
27		* OF ANY KIND, either express or implied. See the LGPL or the MPL for
28		* the specific language governing rights and limitations.
29		*
30		* The Original Code is the cairo graphics library.
31		*
32		* The Initial Developer of the Original Code is University of Southern
33		* California.
34		*
35		* Contributor(s):
36		* Carl D. Worth <cworth@cworth.org>
37		*/
38
39		#include "cairoint.h"
40
41		/**
42		* SECTION:cairo-version
43		* @Title: Version Information
44		* @Short_Description: Compile-time and run-time version checks.
45		*
46		* Cairo has a three-part version number scheme. In this scheme, we use
47		* even vs. odd numbers to distinguish fixed points in the software
48		* vs. in-progress development, (such as from git instead of a tar file,
49		* or as a "snapshot" tar file as opposed to a "release" tar file).
50		*
51		* <informalexample><screen>
52		* _____ Major. Always 1, until we invent a new scheme.
53		* / ___ Minor. Even/Odd = Release/Snapshot (tar files) or Branch/Head (git)
54		* \| / _ Micro. Even/Odd = Tar-file/git
55		* \| \| /
56		* 1.0.0
57		* </screen></informalexample>
58		*
59		* Here are a few examples of versions that one might see.
60		* <informalexample><screen>
61		* Releases
62		* --------
63		* 1.0.0 - A major release
64		* 1.0.2 - A subsequent maintenance release
65		* 1.2.0 - Another major release
66		*
67		* Snapshots
68		* ---------
69		* 1.1.2 - A snapshot (working toward the 1.2.0 release)
70		*
71		* In-progress development (eg. from git)
72		* --------------------------------------
73		* 1.0.1 - Development on a maintenance branch (toward 1.0.2 release)
74		* 1.1.1 - Development on head (toward 1.1.2 snapshot and 1.2.0 release)
75		* </screen></informalexample>
76		*
77		* <refsect2>
78		* <title>Compatibility</title>
79		*
80		* The API/ABI compatibility guarantees for various versions are as
81		* follows. First, let's assume some cairo-using application code that is
82		* successfully using the API/ABI "from" one version of cairo. Then let's
83		* ask the question whether this same code can be moved "to" the API/ABI
84		* of another version of cairo.
85		*
86		* Moving from a release to any later version (release, snapshot,
87		* development) is always guaranteed to provide compatibility.
88		*
89		* Moving from a snapshot to any later version is not guaranteed to
90		* provide compatibility, since snapshots may introduce new API that ends
91		* up being removed before the next release.
92		*
93		* Moving from an in-development version (odd micro component) to any
94		* later version is not guaranteed to provide compatibility. In fact,
95		* there's not even a guarantee that the code will even continue to work
96		* with the same in-development version number. This is because these
97		* numbers don't correspond to any fixed state of the software, but
98		* rather the many states between snapshots and releases.
99		*
100		* </refsect2>
101		* <refsect2>
102		* <title>Examining the version</title>
103		*
104		* Cairo provides the ability to examine the version at either
105		* compile-time or run-time and in both a human-readable form as well as
106		* an encoded form suitable for direct comparison. Cairo also provides the
107		* macro CAIRO_VERSION_ENCODE() to perform the encoding.
108		*
109		* <informalexample><screen>
110		* Compile-time
111		* ------------
112		* #CAIRO_VERSION_STRING Human-readable
113		* #CAIRO_VERSION Encoded, suitable for comparison
114		*
115		* Run-time
116		* --------
117		* cairo_version_string() Human-readable
118		* cairo_version() Encoded, suitable for comparison
119		* </screen></informalexample>
120		*
121		* For example, checking that the cairo version is greater than or equal
122		* to 1.0.0 could be achieved at compile-time or run-time as follows:
123		*
124		* <informalexample><programlisting>
125		* ##if CAIRO_VERSION >= CAIRO_VERSION_ENCODE(1, 0, 0)
126		* printf ("Compiling with suitable cairo version: %s\n", %CAIRO_VERSION_STRING);
127		* ##endif
128		*
129		* if (cairo_version() >= CAIRO_VERSION_ENCODE(1, 0, 0))
130		* printf ("Running with suitable cairo version: %s\n", cairo_version_string ());
131		* </programlisting></informalexample>
132		*
133		* </refsect2>
134		*
135		**/
136
137		/**
138		* CAIRO_VERSION:
139		*
140		* The version of cairo available at compile-time, encoded using
141		* CAIRO_VERSION_ENCODE().
142		*
143		* Since: 1.0
144		**/
145
146		/**
147		* CAIRO_VERSION_MAJOR:
148		*
149		* The major component of the version of cairo available at compile-time.
150		*
151		* Since: 1.0
152		**/
153
154		/**
155		* CAIRO_VERSION_MINOR:
156		*
157		* The minor component of the version of cairo available at compile-time.
158		*
159		* Since: 1.0
160		**/
161
162		/**
163		* CAIRO_VERSION_MICRO:
164		*
165		* The micro component of the version of cairo available at compile-time.
166		*
167		* Since: 1.0
168		**/
169
170		/**
171		* CAIRO_VERSION_STRING:
172		*
173		* A human-readable string literal containing the version of cairo available
174		* at compile-time, in the form of "X.Y.Z".
175		*
176		* Since: 1.8
177		**/
178
179		/**
180		* CAIRO_VERSION_ENCODE:
181		* @major: the major component of the version number
182		* @minor: the minor component of the version number
183		* @micro: the micro component of the version number
184		*
185		* This macro encodes the given cairo version into an integer. The numbers
186		* returned by %CAIRO_VERSION and cairo_version() are encoded using this macro.
187		* Two encoded version numbers can be compared as integers. The encoding ensures
188		* that later versions compare greater than earlier versions.
189		*
190		* Returns: the encoded version.
191		*
192		* Since: 1.0
193		**/
194
195		/**
196		* CAIRO_VERSION_STRINGIZE:
197		* @major: the major component of the version number
198		* @minor: the minor component of the version number
199		* @micro: the micro component of the version number
200		*
201		* This macro encodes the given cairo version into an string. The numbers
202		* returned by %CAIRO_VERSION_STRING and cairo_version_string() are encoded using this macro.
203		* The parameters to this macro must expand to numerical literals.
204		*
205		* Returns: a string literal containing the version.
206		*
207		* Since: 1.8
208		**/
209
210		/**
211		* cairo_version:
212		*
213		* Returns the version of the cairo library encoded in a single
214		* integer as per %CAIRO_VERSION_ENCODE. The encoding ensures that
215		* later versions compare greater than earlier versions.
216		*
217		* A run-time comparison to check that cairo's version is greater than
218		* or equal to version X.Y.Z could be performed as follows:
219		*
220		* <informalexample><programlisting>
221		* if (cairo_version() >= CAIRO_VERSION_ENCODE(X,Y,Z)) {...}
222		* </programlisting></informalexample>
223		*
224		* See also cairo_version_string() as well as the compile-time
225		* equivalents %CAIRO_VERSION and %CAIRO_VERSION_STRING.
226		*
227		* Return value: the encoded version.
228		*
229		* Since: 1.0
230		**/
231		int
232		cairo_version (void)
233	9.37k	{
234	9.37k	return CAIRO_VERSION;
235	9.37k	}
236
237		/**
238		* cairo_version_string:
239		*
240		* Returns the version of the cairo library as a human-readable string
241		* of the form "X.Y.Z".
242		*
243		* See also cairo_version() as well as the compile-time equivalents
244		* %CAIRO_VERSION_STRING and %CAIRO_VERSION.
245		*
246		* Return value: a string containing the version.
247		*
248		* Since: 1.0
249		**/
250		const char*
251		cairo_version_string (void)
252	2	{
253	2	return CAIRO_VERSION_STRING;
254	2	}
255		slim_hidden_def (cairo_version_string);