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