The following commit has been merged in the master branch:
commit 74946af470550a3295e00cf57eca1747215b9311
Author: Niels Thykier <ni...@thykier.net>
Date: Thu May 24 13:47:10 2012 +0200
libdpkg: Add documentation for version module
[guil...@debian.org:
- Change formatting to conform to current documentation style.
- Refer to deb-version(5) instead of policy manual. ]
Signed-off-by: Niels Thykier <ni...@thykier.net>
Signed-off-by: Guillem Jover <guil...@debian.org>
diff --git a/lib/dpkg/version.c b/lib/dpkg/version.c
index 89a8cec..f623697 100644
--- a/lib/dpkg/version.c
+++ b/lib/dpkg/version.c
@@ -26,6 +26,13 @@
#include <dpkg/string.h>
#include <dpkg/version.h>
+/**
+ * Turn the passed version into an empty version.
+ *
+ * This can be used to ensure the version is properly initialized.
+ *
+ * @param version The version to clear.
+ */
void
dpkg_version_blank(struct dpkg_version *version)
{
@@ -34,6 +41,14 @@ dpkg_version_blank(struct dpkg_version *version)
version->revision = NULL;
}
+/**
+ * Test if a version is not empty.
+ *
+ * @param version The version to test.
+ *
+ * @retval true If the version is informative (i.e. not an empty version).
+ * @retval false If the version is empty.
+ */
bool
dpkg_version_is_informative(const struct dpkg_version *version)
{
@@ -105,6 +120,21 @@ verrevcmp(const char *a, const char *b)
return 0;
}
+/**
+ * Compares two Debian versions.
+ *
+ * This function follows the convention of the comparator functions used by
+ * qsort().
+ *
+ * @see deb-version(5)
+ *
+ * @param a The first version.
+ * @param b The second version.
+ *
+ * @retval 0 If a and b are equal.
+ * @retval <0 If a is smaller than b.
+ * @retval >0 If a is greater than b.
+ */
int
dpkg_version_compare(const struct dpkg_version *a,
const struct dpkg_version *b)
@@ -123,6 +153,20 @@ dpkg_version_compare(const struct dpkg_version *a,
return verrevcmp(a->revision, b->revision);
}
+/**
+ * Check if two versions have a certain relation.
+ *
+ * @param a The first version.
+ * @param rel The relation.
+ * @param b The second version.
+ *
+ * @retval true If the expression “a rel b” is true.
+ * @retval true If rel is #dpkg_relation_none.
+ * @retval false Otherwise.
+ *
+ * @warning If rel is not a valid relation, this function will terminate
+ * the program.
+ */
bool
dpkg_version_relate(const struct dpkg_version *a,
enum dpkg_relation rel,
diff --git a/lib/dpkg/version.h b/lib/dpkg/version.h
index ba59884..e2dab25 100644
--- a/lib/dpkg/version.h
+++ b/lib/dpkg/version.h
@@ -34,18 +34,36 @@ DPKG_BEGIN_DECLS
* @{
*/
+/**
+ * Data structure representing a Debian version.
+ *
+ * @see deb-version(5)
+ */
struct dpkg_version {
+ /** The epoch. It will be zero if no epoch is present. */
unsigned int epoch;
+ /** The upstream part of the version. */
const char *version;
+ /** The Debian revision part of the version. */
const char *revision;
};
+/**
+ * Enum constants for the supported relation operations that can be done
+ * on Debian versions.
+ */
enum dpkg_relation {
+ /** The “none” relation, sentinel value. */
dpkg_relation_none = 0,
+ /** Equality relation (‘=’). */
dpkg_relation_eq = DPKG_BIT(0),
+ /** Less than relation (‘<<’). */
dpkg_relation_lt = DPKG_BIT(1),
+ /** Less than or equal to relation (‘<=’). */
dpkg_relation_le = dpkg_relation_lt | dpkg_relation_eq,
+ /** Greater than relation (‘>>’). */
dpkg_relation_gt = DPKG_BIT(2),
+ /** Greater than or equal to relation (‘>=’). */
dpkg_relation_ge = dpkg_relation_gt | dpkg_relation_eq,
};
--
dpkg's main repository
--
To UNSUBSCRIBE, email to debian-dpkg-cvs-requ...@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
