xtd - Reference Guide  0.1.0
Modern c++17/20 framework to create console, GUI and unit test applications on Windows, macOS, Linux, iOS and android.
Public Member Functions | Static Public Member Functions | List of all members
xtd::version Class Referencefinal

#include <version.h>

Definition

Represents the version number of an assembly, operating system, or the xtd. This class cannot be inherited.

Namespace
xtd
Library
xtd.core
Examples
The following example shows how to use xtd::version to get the version of the Operating System.
#include <xtd/xtd>
using namespace xtd;
namespace examples {
class program : public object {
public:
// The main entry point for the application.
static void main() {
// Get the operating system version.
version ver = os.version();
console::write_line("Operating System: {0} ({1})", os.version_string(), ver.to_string());
}
};
}
startup_(examples::program);
// This code can produce the following output:
//
// Operating System: macOS 11.6.0 (11.6.0.0)
Remarks
xtd::version numbers consist of two to four components: major, minor, build, and revision. The major and minor components are required; the build and revision components are optional, but the build component is required if the revision component is defined. All defined components must be integers greater than or equal to 0. The format of the version number is as follows (optional components are shown in square brackets ([ and ]):
major.minor[.build[.revision]] 
The components are used by convention as follows:
  • major: Assemblies with the same name but different major versions are not interchangeable. A higher version number might indicate a major rewrite of a product where backward compatibility cannot be assumed.
  • minor: If the name and major version number on two assemblies are the same, but the minor version number is different, this indicates significant enhancement with the intention of backward compatibility. This higher minor version number might indicate a point release of a product or a fully backward-compatible new version of a product.
  • build: A difference in build number represents a recompilation of the same source. Different build numbers might be used when the processor, platform, or compiler changes.
  • revision: Assemblies with the same name, major, and minor version numbers but different revisions are intended to be fully interchangeable. A higher revision number might be used in a build that fixes a security hole in a previously released assembly.
Subsequent versions of an assembly that differ only by build or revision numbers are considered to be Hotfix updates of the prior version.
Warning
The value of xtd::version properties that have not been explicitly assigned a value is undefined (-1).
Retrieving Version Information
xtd::version objects are most frequently used to store version information about some system or application component (such as the operating system), the common language runtime, the current application's executable, or a particular assembly. The following examples illustrate some of the most common scenarios:
Comparing xtd::version objects
You can use the xtd::version::compare_to method to determine whether one xtd::version object is earlier than, the same as, or later than a secondxtd::version object. The following example indicates that xtd::version 2.1 is later than xtd::version 2.0.
version v1(2, 0);
version v2("2.1");
console::write("version {0} is ", v1);
switch(v1.compare_to(v2)) {
case 0: console::write("the same as"); break;
case 1: console::write("later than"); break;
case -1: console::write("earlier than"); break;
}
console::write_line(" version {0}.", v2);
// The example displays the following output:
// version 2.0 is earlier than version 2.1.
For two versions to be equal, the major, minor, build, and revision numbers of the first xtd::version object must be identical to those of the second xtd::version object. If the build or revision number of a xtd::version object is undefined, that Vxtd::version object is considered to be earlier than a xtd::vVersion object whose build or revision number is equal to zero. The following example illustrates this by comparing three xtd::version objects that have undefined version components.
using namespace xtd;
enum class version_time {earlier = -1, same = 0, later = 1 };
std::ostream& operator<<(std::ostream& os, version_time value) {return os << to_string(value, {{version_time::earlier, "earlier"}, {version_time::same, "same"}, {version_time::later, "later"}});}
class example {
public:
static void main() {
version v1(1, 1);
version v1a("1.1.0");
show_relationship(v1, v1a);
version v1b(1, 1, 0, 0);
show_relationship(v1b, v1a);
}
private:
static void show_relationship(const version& v1, const version& v2) {
console::write_line("Relationship of {0} to {1}: {2}", v1, v2, as<version_time>(v1.compare_to(v2)));
}
};
startup_(example);
// The example displays the following output:
// Relationship of 1.1 to 1.1.0: earlier
// Relationship of 1.1.0.0 to 1.1.0: later

Public Member Functions

 version () noexcept=default
 Initializes a new instance of the xtd::version class. More...
 
 version (const xtd::ustring &verion)
 Initializes a new instance of the xtd::version class using the specified string. More...
 
 version (int32_t major, int32_t minor)
 Initializes a new instance of the xtd::version class using the specified major and minor values. More...
 
 version (int32_t major, int32_t minor, int32_t build)
 Initializes a new instance of the xtd::version class using the specified major, minor and build values. More...
 
 version (int32_t major, int32_t minor, int32_t build, int32_t revision)
 Initializes a new instance of the xtd::version class using the specified major, minor, build andd revision values. More...
 
int32_t build () const noexcept
 Gets the value of the build component of the version number for the current xtdd::version object. More...
 
int32_t compare_to (const object &version) const noexcept override
 Compares the current xtd::version object to a specified object and returns an indication of their relative values. More...
 
int32_t compare_to (const version &version) const noexcept override
 Compares the current xtd::version object to a specified object and returns an indication of their relative values. More...
 
int32_t major () const noexcept
 Gets the value of the major component of the version number for the current xtdd::version object. More...
 
int16_t major_revision () const noexcept
 Gets the high 16 bits of the revision number. More...
 
int32_t minor () const noexcept
 Gets the value of the minor component of the version number for the current xtdd::version object. More...
 
int16_t minor_revision () const noexcept
 Gets the low 16 bits of the revision number. More...
 
int32_t revision () const noexcept
 Gets the value of the revision component of the version number for the current xtd::version object. More...
 
xtd::ustring to_string () const noexcept override
 Converts the value of the current xtd::version object to its equivalent xtd::ustring representation. More...
 
xtd::ustring to_string (size_t field_count) const
 Converts the value of the current xtd::version object to its equivalent xtd::ustring representation. A specified count indicates the number of components to return. More...
 
- Public Member Functions inherited from xtd::object
 object ()=default
 Create a new instance of the ultimate base class object. More...
 
virtual bool equals (const object &obj) const noexcept
 Determines whether the specified object is equal to the current object. More...
 
virtual size_t get_hash_code () const noexcept
 Serves as a hash function for a particular type. More...
 
template<typename object_t >
std::unique_ptr< object_t > memberwise_clone () const
 Gets the type of the current instance. More...
 

Static Public Member Functions

static version parse (const xtd::ustring &input)
 Converts the string representation of a version number to an equivalent Version object. More...
 
static bool try_parse (const xtd::ustring &input, version &result) noexcept
 Tries to convert the string representation of a version number to an equivalent xtd::version object, and returns a value that indicates whether the conversion succeeded. More...
 
- Static Public Member Functions inherited from xtd::object
static bool equals (const object &object_a, const object &object_b) noexcept
 Determines whether the specified object instances are considered equal. More...
 
static bool reference_equals (const object &object_a, const object &object_b) noexcept
 Determines whether the specified object instances are the same instance. More...
 

Constructor & Destructor Documentation

◆ version() [1/5]

xtd::version::version ( )
defaultnoexcept

Initializes a new instance of the xtd::version class.

Remarks
This constructor creates a xtd::ersion object with the following property values.
Properrty Value
xtd::version::major 0
xtd::version::minor 0
xtd::version::build -1
xtd::version::revision -1

◆ version() [2/5]

xtd::version::version ( const xtd::ustring verion)

Initializes a new instance of the xtd::version class using the specified string.

Parameters
versionA string containing the major, minor, build, and revision numbers, where each number is delimited with a period character ('.').
Exceptions
xtd::argument_exceptionversion has fewer than two components or more than four components.
xtd::argument_out_of_range_exceptionA major, minor, build, or revision component is less than zero.
xtd::format_exceptionAt least one component of version does not parse to an integer.
xtd::overflow_exceptionAt least one component of version represents a number greater than std::numeric_limits<int32_t>::max().
Remarks
The version parameter can contain only the components major, minor, build, and revision, in that order, and all separated by periods. There must be at least two components, and at most four. The first two components are assumed to be major and minor. The value of unspecified components is undefined.
The format of the version number is as follows. Optional components are shown in square brackets ('[' and ']'):
major.minor[.build[.revision]] 
All defined components must be integers greater than or equal to 0. For example, if the major number is 6, the minor number is 2, the build number is 1, and the revision number is 3, then version should be "6.2.1.3".

◆ version() [3/5]

xtd::version::version ( int32_t  major,
int32_t  minor 
)

Initializes a new instance of the xtd::version class using the specified major and minor values.

Parameters
majorThe major version number.
minorThe minor version number.
Exceptions
xtd::out_of_range_excepttionmajor or minor is less than zero.
Remarks
This constructor creates a xtd::ersion object with the following property values.
Properrty Value
xtd::version::major major
xtd::version::minor minor
xtd::version::build undefined (-1)
xtd::version::revision undefined (-1)

◆ version() [4/5]

xtd::version::version ( int32_t  major,
int32_t  minor,
int32_t  build 
)

Initializes a new instance of the xtd::version class using the specified major, minor and build values.

Parameters
majorThe major version number.
minorThe minor version number.
buildThe build version number.
Exceptions
xtd::out_of_range_excepttionmajor, minor or build is less than zero.
Remarks
This constructor creates a xtd::ersion object with the following property values.
Properrty Value
xtd::version::major major
xtd::version::minor minor
xtd::version::build build
xtd::version::revision undefined (-1)

◆ version() [5/5]

xtd::version::version ( int32_t  major,
int32_t  minor,
int32_t  build,
int32_t  revision 
)

Initializes a new instance of the xtd::version class using the specified major, minor, build andd revision values.

Parameters
majorThe major version number.
minorThe minor version number.
buildThe build version number.
revisionThe revision version number.
Exceptions
xtd::out_of_range_excepttionmajor, minor, build or revision is less than zero.
Remarks
This constructor creates a xtd::version object with the following property values.
Properrty Value
xtd::version::major major
xtd::version::minor minor
xtd::version::build build
xtd::version::revision revision
Examples
The following code example demonstrates the xtd::version constructor, and xtd::version::major, xtd::version::minor, xtd::version::build, xtd::version::revision, xtd::version::major_revision, and xtd::version::minor_revision properties.
#include <xtd/xtd>
using namespace xtd;
namespace examples {
class program : public object {
public:
// The main entry point for the application.
static void main() {
ustring fmt_std = "Standard version:\n"
" major.minor.build.revision = {0}.{1}.{2}.{3}";
ustring fmt_int = "Interim version:\n"
" major.minor.build.maj_rev/min_rev = {0}.{1}.{2}.{3}/{4}";
version std(2, 4, 1128, 2);
version interim(2, 4, 1128, (100 << 16) + 2);
console::write_line(fmt_std, std.major(), std.minor(), std.build(), std.revision());
console::write_line(fmt_int, interim.major(), interim.minor(), interim.build(), interim.major_revision(), interim.minor_revision());
}
};
}
startup_(examples::program);
// This code can produce the following output:
//
// Standard version:
// major.minor.build.revision = 2.4.1128.2
// Interim version:
// major.minor.build.maj_rev/min_rev = 2.4.1128.100/2

Member Function Documentation

◆ build()

int32_t xtd::version::build ( ) const
noexcept

Gets the value of the build component of the version number for the current xtdd::version object.

Returns
The build number, or -1 if the build number is undefined.
Remarks
For example, if the version number is 6.2.1.3, the build number is 1. If the version number is 6.2, the build number is undefined.

◆ compare_to() [1/2]

int32_t xtd::version::compare_to ( const object version) const
overridevirtualnoexcept

Compares the current xtd::version object to a specified object and returns an indication of their relative values.

Parameters
versionAn object to compare.
Returns
A signed integer that indicates the relative values of the two objects, as shown in the following table.
Return value Meaning
Less than zero The current xtd::version object is a version before version.
Zero The current xtd::version object is the same version as version.
Greater than zero The current xttd::version object is a version subsequent to version or version is not ta xtd::version object.
Remarks
The components of Version in decreasing order of importance are: major, minor, build, and revision. An unknown component is assumed to be older than any known component. For example:

Implements xtd::icomparable< version >.

◆ compare_to() [2/2]

int32_t xtd::version::compare_to ( const version version) const
overridevirtualnoexcept

Compares the current xtd::version object to a specified object and returns an indication of their relative values.

Parameters
versionAn object to compare.
Returns
A signed integer that indicates the relative values of the two objects, as shown in the following table.
Return value Meaning
Less than zero The current xtd::version object is a version before version.
Zero The current xtd::version object is the same version as version.
Greater than zero The current xttd::version object is a version subsequent to version.
Remarks
The components of Version in decreasing order of importance are: major, minor, build, and revision. An unknown component is assumed to be older than any known component. For example:

Implements xtd::icomparable< version >.

◆ major()

int32_t xtd::version::major ( ) const
noexcept

Gets the value of the major component of the version number for the current xtdd::version object.

Returns
The major version number.
Remarks
For example, if the version number is 6.2, the major version is 6.

◆ major_revision()

int16_t xtd::version::major_revision ( ) const
noexcept

Gets the high 16 bits of the revision number.

Returns
A 16-bit signed integer.
Remarks
Suppose you release an interim version of your application to temporarily correct a problem until you can release a permanent solution. The temporary version does not warrant a new revision number, but it does need to be identified as a different version. In this case, encode the identification information in the high and low 16-bit portions of the 32-bit revision number. Use the xtd::version::revision property to obtain the entire revision number, use the xtd::version::major_revision property to obtain the high 16 bits, and use the xtd::version::minor_revision property to obtain the low 16 bits.

◆ minor()

int32_t xtd::version::minor ( ) const
noexcept

Gets the value of the minor component of the version number for the current xtdd::version object.

Returns
The minor version number.
Remarks
For example, if the version number is 6.2, the minor version is 2.

◆ minor_revision()

int16_t xtd::version::minor_revision ( ) const
noexcept

Gets the low 16 bits of the revision number.

Returns
A 16-bit signed integer.
Remarks
Suppose you release an interim version of your application to temporarily correct a problem until you can release a permanent solution. The temporary version does not warrant a new revision number, but it does need to be identified as a different version. In this case, encode the identification information in the high and low 16-bit portions of the 32-bit revision number. Use the xtd::version::revision property to obtain the entire revision number, use the xtd::version::major_revision property to obtain the high 16 bits, and use the xtd::version::minor_revision property to obtain the low 16 bits.

◆ parse()

static version xtd::version::parse ( const xtd::ustring input)
static

Converts the string representation of a version number to an equivalent Version object.

Parameters
inputA string that contains a version number to convert.
Returns
An object that is equivalent to the version number specified in the input parameter.
Exceptions
xtd::argument_out_of_range_exceptionA major, minor, build, or revision component is less than zero.
xtd::format_exceptionAt least one component of input does not parse to an integer.
xtd::overflow_exceptionAt least one component of input represents a number greater than std::numeric_limits<int32_t>::max().
Remarks
The input parameter must have the following format:
major.minor[.build[.revision]] 
where major, minor, build, and revision are the string representations of the version number's four components: major version number, minor version number, build number, and revision number, respectively. Optional components are shown in square brackets ([ and ]). The components must appear in the specified order and must be separated by periods
Warning
Because the string representation of a version number must conform to a recognized pattern, applications should always use exception handling when calling the xtd::version::parse method to parse user input. Alternatively, you can call the xtd::version::try_parse method to parse the string representation of a version number and return a value that indicates whether the parse operation succeeded.
Remarks
The xtd::version::parse method is a convenience method; it is equivalent to calling the xtd::version(const ustring&) constructor.

◆ revision()

int32_t xtd::version::revision ( ) const
noexcept

Gets the value of the revision component of the version number for the current xtd::version object.

Returns
The revision number, or -1 if the revision number is undefined.
Remarks
For example, if the version number is 6.2.1.3, the revision number is 3. If the version number is 6.2, the revision number is undefined.

◆ to_string() [1/2]

xtd::ustring xtd::version::to_string ( ) const
overridevirtualnoexcept

Converts the value of the current xtd::version object to its equivalent xtd::ustring representation.

Returns
The xtd::ustring representation of the values of the major, minor, build, and revision components of the current xtd::version object, as depicted in the following format. Each component is separated by a period character ('.'). Square brackets ('[' and ']') indicate a component that will not appear in the return value if the component is not defined:
major.minor[.build[.revision]] 
For example, if you create a xtd::version object using the constructor xtd::version(1, 1), the returned string is "1.1". If you create a xtd::version object using the constructor xtd::version(1, 3, 4, 2), the returned string is "1.3.4.2".

Reimplemented from xtd::object.

◆ to_string() [2/2]

xtd::ustring xtd::version::to_string ( size_t  field_count) const

Converts the value of the current xtd::version object to its equivalent xtd::ustring representation. A specified count indicates the number of components to return.

Parameters
field_countThe number of components to return. The field_count ranges from 0 to 4.
Returns
The xtd::ustring representation of the values of the major, minor, build, and revision components of the current xtd::version object, each separated by a period character ('.'). The field_count parameter determines how many components are returned.
field_count Return Value
0 An empty string ("").
1 major
2 major.minor
3 major.minor.build
4 major.minor.build.revision
For example, if you create xtd::version object using the constructor xtd::version(1,3,5), xtd::version::to_string(2) returns "1.3" and xtd::version::to_string(4) throws an exception.
Exceptions
xtd::argument_exceptionfield_count is more than 4 -or- field_count is more than the number of components defined in the current xtd::version object.

◆ try_parse()

static bool xtd::version::try_parse ( const xtd::ustring input,
version result 
)
staticnoexcept

Tries to convert the string representation of a version number to an equivalent xtd::version object, and returns a value that indicates whether the conversion succeeded.

Parameters
inputA string that contains a version number to convert.
resultWhen this method returns, contains the xtd::version equivalent of the number that is contained in input, if the conversion succeeded. If input is empty, or if the conversion fails, result is empty when the method returns.
Returns
true if the input parameter was converted successfully; otherwise, false.
Remarks
The xtd::version::try_parse method is similar to the xtd::version::parse method, except that it doesn't throw an exception if the conversion fails. Instead, it returns false if input is null, has fewer than two or more than four components, has at least one component that is not an integer, has at least one component that is less than zero, or has at least one component that is greater than std::numeric_limits<int32_t>::max(). For the parse operation to succeed, the input parameter must be in the following format:
major.minor[.build[.revision]] 
where major, minor, build, and revision are the string representations of the version number's four components: major version number, minor version number, build number, and revision number, respectively. Optional components are shown in square brackets ([ and ]). The components must appear in order and must be separated by periods.

The documentation for this class was generated from the following file: