The Battle for Wesnoth  1.15.12+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  version_info(std::nullptr_t) = delete;
50 
51  /** Simple list constructor. */
52  version_info(unsigned int major, unsigned int minor, unsigned int revision_level,
53  char special_separator='\0', const std::string& special=std::string());
54 
55  /**
56  * Whether the version number is considered canonical for mainline Wesnoth.
57  *
58  * Mainline Wesnoth version numbers have at most three components, so this
59  * check is equivalent to <tt>components() <= 3</tt>.
60  */
61  bool is_canonical() const;
62 
63  /**
64  * Whether this version represents a development version of Wesnoth aka whether the minor version odd.
65  */
66  bool is_dev_version() const;
67 
68  /**
69  * Serializes the version number into string form.
70  *
71  * The result is in the format <tt>x1.x2.x3[.x4[.x5[...]]]</tt>, followed
72  * by the special version suffix separator (if not null) and the suffix
73  * itself (if not empty).
74  */
75  std::string str() const;
76 
77  /**
78  * Syntactic shortcut for str().
79  */
80  operator std::string() const { return this->str(); }
81 
82  // Good old setters and getters for this class. Their names should be
83  // pretty self-descriptive. I couldn't use shorter names such as
84  // major() or minor() because sys/sysmacros.h reserves them by defining
85  // some backwards-compatibility macros for stuff, and they cause
86  // conflicts in the C/C++ preprocessor on GNU/Linux (GCC).
87 
88  /**
89  * Retrieves the major version number (@a x1 in "x1.x2.x3").
90  */
91  unsigned int major_version() const;
92 
93  /**
94  * Retrieves the minor version number (@a x2 in "x1.x2.x3").
95  */
96  unsigned int minor_version() const;
97 
98  /**
99  * Retrieves the revision level (@a x3 in "x1.x2.x3").
100  */
101  unsigned int revision_level() const;
102 
103  /**
104  * Retrieves the special version separator (e.g. '+' in "0.1+dev").
105  *
106  * The special version separator is the first non-alphanumerical character
107  * preceding the special version suffix and following the last numeric
108  * component. If missing, the null character is returned instead.
109  */
111  {
112  return this->special_separator_;
113  }
114 
115  /**
116  * Retrieves the special version suffix (e.g. "dev" in "0.1+dev").
117  */
118  const std::string& special_version() const
119  {
120  return this->special_;
121  }
122 
123  /**
124  * Sets the major version number.
125  */
126  void set_major_version(unsigned int);
127 
128  /**
129  * Sets the minor version number.
130  */
131  void set_minor_version(unsigned int);
132 
133  /**
134  * Sets the revision level.
135  */
136  void set_revision_level(unsigned int);
137 
138  /**
139  * Sets the special version suffix.
140  */
141  void set_special_version(const std::string& str)
142  {
143  this->special_ = str;
144  }
145 
146  /**
147  * Returns any numeric component from a version number.
148  *
149  * The index may be in the [0,3) range, yielding the same results as
150  * major_version(), minor_version(), and revision_level().
151  *
152  * @throw std::out_of_range If the number of components is less than
153  * <tt>index - 1</tt>.
154  */
155  unsigned int get_component(std::size_t index) const
156  {
157  return nums_.at(index);
158  }
159 
160  /**
161  * Sets any numeric component from a version number.
162  *
163  * The index may be in the [0,3) range, resulting in the same effect as
164  * set_major_version(), set_minor_version(), and set_revision_level().
165  *
166  * @throw std::out_of_range If the number of components is less than
167  * <tt>index - 1</tt>.
168  */
169  void set_component(std::size_t index, unsigned int value)
170  {
171  nums_.at(index) = value;
172  }
173 
174  /**
175  * Read-only access to all numeric components.
176  */
177  const std::vector<unsigned int>& components() const
178  {
179  return this->nums_;
180  }
181 
182 private:
183  std::vector<unsigned int> nums_;
184  std::string special_;
186 };
187 
188 /** Equality operator for version_info. */
189 bool operator==(const version_info&, const version_info&);
190 /** Inequality operator for version_info. */
191 bool operator!=(const version_info&, const version_info&);
192 /** Greater-than operator for version_info. */
193 bool operator>(const version_info&, const version_info&);
194 /** Less-than operator for version_info. */
195 bool operator<(const version_info&, const version_info&);
196 /** Greater-than-or-equal operator for version_info. */
197 bool operator>=(const version_info&, const version_info&);
198 /** Less-than-or-equal operator for version_info. */
199 bool operator<=(const version_info&, const version_info&);
200 
209 };
210 
211 VERSION_COMP_OP parse_version_op(const std::string& op_str);
213 
214 namespace game_config
215 {
219 
220 extern const std::string revision;
221 
222 } // 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:58
bool is_dev_version() const
Whether this version represents a development version of Wesnoth aka whether the minor version odd...
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.