The Battle for Wesnoth  1.15.2+dev
game_version.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2008 - 2018 by Iris Morelle <shadowm2006@gmail.com>
3  Part of the Battle for Wesnoth Project https://www.wesnoth.org/
4 
5  This program is free software; you can redistribute it and/or modify
6  it under the terms of the GNU General Public License as published by
7  the Free Software Foundation; either version 2 of the License, or
8  (at your option) any later version.
9  This program is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY.
11 
12  See the COPYING file for more details.
13 */
14 
15 #pragma once
16 
17 #include <string>
18 #include <vector>
19 
20 /**
21  * @file
22  * Interfaces for manipulating version numbers of engine,
23  * add-ons, etc.
24  */
25 
26 /**
27  * Represents version numbers.
28  *
29  * Versions are expected to be in the format <tt>x1.x2.x3[.x4[.x5[...]]]</tt>,
30  * with an optional trailing special version suffix and suffix separator.
31  *
32  * When parsing a version string, the first three components are optional
33  * and default to zero if absent. The serialized form will always have all
34  * first three components, making deserialization and serialization an
35  * asymmetric process in those cases (e.g. "0.1" becomes "0.1.0").
36  *
37  * The optional trailing suffix starts after the last digit, and may be
38  * preceded by a non-alphanumeric separator character (e.g. "0.1a" has "a" as
39  * its suffix and the null character as its separator, but in "0.1+dev" the
40  * separator is '+' and the suffix is "dev"). Both are preserved during
41  * serialization ("0.1+dev" becomes "0.1.0+dev").
42  */
44 {
45 public:
46  version_info(); /**< Default constructor. */
47  version_info(const std::string&); /**< String constructor. */
48  version_info(const char* str);
49 
50  /** Simple list constructor. */
51  version_info(unsigned int major, unsigned int minor, unsigned int revision_level,
52  char special_separator='\0', const std::string& special=std::string());
53 
54  /**
55  * Whether the version number is considered canonical for mainline Wesnoth.
56  *
57  * Mainline Wesnoth version numbers have at most three components, so this
58  * check is equivalent to <tt>components() <= 3</tt>.
59  */
60  bool is_canonical() const;
61 
62  /**
63  * Serializes the version number into string form.
64  *
65  * The result is in the format <tt>x1.x2.x3[.x4[.x5[...]]]</tt>, followed
66  * by the special version suffix separator (if not null) and the suffix
67  * itself (if not empty).
68  */
69  std::string str() const;
70 
71  /**
72  * Syntactic shortcut for str().
73  */
74  operator std::string() const { return this->str(); }
75 
76  // Good old setters and getters for this class. Their names should be
77  // pretty self-descriptive. I couldn't use shorter names such as
78  // major() or minor() because sys/sysmacros.h reserves them by defining
79  // some backwards-compatibility macros for stuff, and they cause
80  // conflicts in the C/C++ preprocessor on GNU/Linux (GCC).
81 
82  /**
83  * Retrieves the major version number (@a x1 in "x1.x2.x3").
84  */
85  unsigned int major_version() const;
86 
87  /**
88  * Retrieves the minor version number (@a x2 in "x1.x2.x3").
89  */
90  unsigned int minor_version() const;
91 
92  /**
93  * Retrieves the revision level (@a x3 in "x1.x2.x3").
94  */
95  unsigned int revision_level() const;
96 
97  /**
98  * Retrieves the special version separator (e.g. '+' in "0.1+dev").
99  *
100  * The special version separator is the first non-alphanumerical character
101  * preceding the special version suffix and following the last numeric
102  * component. If missing, the null character is returned instead.
103  */
105  {
106  return this->special_separator_;
107  }
108 
109  /**
110  * Retrieves the special version suffix (e.g. "dev" in "0.1+dev").
111  */
112  const std::string& special_version() const
113  {
114  return this->special_;
115  }
116 
117  /**
118  * Sets the major version number.
119  */
120  void set_major_version(unsigned int);
121 
122  /**
123  * Sets the minor version number.
124  */
125  void set_minor_version(unsigned int);
126 
127  /**
128  * Sets the revision level.
129  */
130  void set_revision_level(unsigned int);
131 
132  /**
133  * Sets the special version suffix.
134  */
135  void set_special_version(const std::string& str)
136  {
137  this->special_ = str;
138  }
139 
140  /**
141  * Returns any numeric component from a version number.
142  *
143  * The index may be in the [0,3) range, yielding the same results as
144  * major_version(), minor_version(), and revision_level().
145  *
146  * @throw std::out_of_range If the number of components is less than
147  * <tt>index - 1</tt>.
148  */
149  unsigned int get_component(std::size_t index) const
150  {
151  return nums_.at(index);
152  }
153 
154  /**
155  * Sets any numeric component from a version number.
156  *
157  * The index may be in the [0,3) range, resulting in the same effect as
158  * set_major_version(), set_minor_version(), and set_revision_level().
159  *
160  * @throw std::out_of_range If the number of components is less than
161  * <tt>index - 1</tt>.
162  */
163  void set_component(std::size_t index, unsigned int value)
164  {
165  nums_.at(index) = value;
166  }
167 
168  /**
169  * Read-only access to all numeric components.
170  */
171  const std::vector<unsigned int>& components() const
172  {
173  return this->nums_;
174  }
175 
176 private:
177  std::vector<unsigned int> nums_;
178  std::string special_;
180 };
181 
182 /** Equality operator for version_info. */
183 bool operator==(const version_info&, const version_info&);
184 /** Inequality operator for version_info. */
185 bool operator!=(const version_info&, const version_info&);
186 /** Greater-than operator for version_info. */
187 bool operator>(const version_info&, const version_info&);
188 /** Less-than operator for version_info. */
189 bool operator<(const version_info&, const version_info&);
190 /** Greater-than-or-equal operator for version_info. */
191 bool operator>=(const version_info&, const version_info&);
192 /** Less-than-or-equal operator for version_info. */
193 bool operator<=(const version_info&, const version_info&);
194 
203 };
204 
205 VERSION_COMP_OP parse_version_op(const std::string& op_str);
207 
208 namespace game_config
209 {
213 
214 extern const std::string revision;
215 
216 } // namespace game_config
std::string special_
VERSION_COMP_OP
bool operator<=(const version_info &, const version_info &)
Less-than-or-equal operator for version_info.
char special_version_separator() const
Retrieves the special version separator (e.g.
void set_component(std::size_t index, unsigned int value)
Sets any numeric component from a version number.
#define a
void set_major_version(unsigned int)
Sets the major version number.
unsigned int revision_level() const
Retrieves the revision level (x3 in "x1.x2.x3").
void set_revision_level(unsigned int)
Sets the revision level.
bool operator!=(const version_info &, const version_info &)
Inequality operator for version_info.
char special_separator_
#define b
unsigned int get_component(std::size_t index) const
Returns any numeric component from a version number.
const std::string & special_version() const
Retrieves the special version suffix (e.g.
unsigned int major_version() const
Retrieves the major version number (x1 in "x1.x2.x3").
void set_special_version(const std::string &str)
Sets the special version suffix.
const version_info test_version("test")
const std::vector< unsigned int > & components() const
Read-only access to all numeric components.
unsigned int minor_version() const
Retrieves the minor version number (x2 in "x1.x2.x3").
bool do_version_check(const version_info &a, VERSION_COMP_OP op, const version_info &b)
void set_minor_version(unsigned int)
Sets the minor version number.
bool is_canonical() const
Whether the version number is considered canonical for mainline Wesnoth.
const std::string revision
Game configuration data as global variables.
Definition: build_info.cpp:49
std::size_t index(const std::string &str, const std::size_t index)
Codepoint index corresponding to the nth character in a UTF-8 string.
Definition: unicode.cpp:71
const version_info wesnoth_version(VERSION)
bool operator>(const version_info &, const version_info &)
Greater-than operator for version_info.
Represents version numbers.
std::string str() const
Serializes the version number into string form.
bool operator>=(const version_info &, const version_info &)
Greater-than-or-equal operator for version_info.
version_info()
Default constructor.
VERSION_COMP_OP parse_version_op(const std::string &op_str)
const version_info min_savegame_version(MIN_SAVEGAME_VERSION)
std::vector< unsigned int > nums_
bool operator<(const version_info &, const version_info &)
Less-than operator for version_info.
bool operator==(const version_info &, const version_info &)
Equality operator for version_info.