xtd 0.2.0
Loading...
Searching...
No Matches
xtd::version Class Referencefinal
Inheritance diagram for xtd::version:
xtd::object xtd::icomparable< version > xtd::iequatable< version > xtd::interface xtd::comparison_operators< type_t, comparable_t > xtd::interface xtd::equality_operators< type_t, equatable_t >

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/console>
#include <xtd/environment>
#include <xtd/startup>
using namespace xtd;
namespace version_os_example {
class program {
public:
// The main entry point for the application.
static auto main() {
// Get the operating system version.
auto os = environment::os_version();
auto ver = os.version();
console::write_line("Operating System: {0} ({1})", os.version_string(), ver.to_string());
}
};
}
startup_(version_os_example::program::main);
// This code can produce the following output :
//
// Operating System: macOS 11.6.0 (11.6.0.0)
#define startup_(main_method)
Defines the entry point to be called when the application loads. Generally this is set either to the ...
Definition startup.h:175
The xtd namespace contains all fundamental classes to access Hardware, Os, System,...
Definition xtd_about_box.h:10
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 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 second xtd::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.
static void write(arg_t &&value)
Writes the text representation of the specified value to the standard output stream.
Definition console.h:462
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 xtd::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 };
template<> struct xtd::enum_register<version_time> {
explicit operator auto() const noexcept {return xtd::enum_collection<version_time> {{version_time::earlier, "earlier"}, {version_time::same, "same"}, {version_time::later, "later"}};}
};
class example {
public:
static auto 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::main);
// 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
int32 compare_to(const version &version) const noexcept override
Compares the current xtd::version object to a specified object and returns an indication of their rel...
std::vector< xtd::collections::generic::key_value_pair< enum_t, xtd::string > > enum_collection
Represents a pair of an enum_t value and a string of an enum of type enum_t.
Definition enum_collection.h:22
Provides the registration struct for enumerations.
Definition enum_register.h:38
Examples
application_with_cmake_assembly_info.cpp, application_with_manual_assembly_info.cpp, boxing.cpp, and version.cpp.

Public Constructors

 version () noexcept=default
 Initializes a new instance of the xtd::version class.
 
 version (const xtd::string &version)
 Initializes a new instance of the xtd::version class using the specified string.
 
 version (int32 major, int32 minor)
 Initializes a new instance of the xtd::version class using the specified major and minor values.
 
 version (int32 major, int32 minor, int32 build)
 Initializes a new instance of the xtd::version class using the specified major, minor and build values.
 
 version (int32 major, int32 minor, int32 build, int32 revision)
 Initializes a new instance of the xtd::version class using the specified major, minor, build and revision values.
 

Public Properties

int32 build () const noexcept
 Gets the value of the build component of the version number for the current xtd::version object.
 
int32 major () const noexcept
 Gets the value of the major component of the version number for the current xtd::version object.
 
int16 major_revision () const noexcept
 Gets the high 16 bits of the revision number.
 
int32 minor () const noexcept
 Gets the value of the minor component of the version number for the current xtd::version object.
 
int16 minor_revision () const noexcept
 Gets the low 16 bits of the revision number.
 
int32 revision () const noexcept
 Gets the value of the revision component of the version number for the current xtd::version object.
 

Public Methods

int32 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.
 
bool equals (const version &v) const noexcept override
 Indicates whether the current object is equal to another object of the same type.
 
xtd::string to_string () const noexcept override
 Converts the value of the current xtd::version object to its equivalent xtd::string representation.
 
xtd::string to_string (size_t field_count) const
 Converts the value of the current xtd::version object to its equivalent xtd::string representation. A specified count indicates the number of components to return.
 
virtual bool equals (const object &obj) const noexcept
 Determines whether the specified object is equal to the current object.
 
template<typename object_a_t , typename object_b_t >
static bool equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
 Determines whether the specified object instances are considered equal.
 

Public Static Methods

static version parse (const xtd::string &input)
 Converts the string representation of a version number to an equivalent Version object.
 
static bool try_parse (const xtd::string &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.
 

Additional Inherited Members

- Public Member Functions inherited from xtd::object
 object ()=default
 Create a new instance of the ultimate base class object.
 
virtual size_t get_hash_code () const noexcept
 Serves as a hash function for a particular type.
 
virtual type_object get_type () const noexcept
 Gets the type of the current instance.
 
template<typename object_t >
xtd::uptr< object_t > memberwise_clone () const
 Creates a shallow copy of the current object.
 
- Public Member Functions inherited from xtd::icomparable< version >
- Public Member Functions inherited from xtd::iequatable< version >
- Static Public Member Functions inherited from xtd::object
template<typename object_a_t , typename object_b_t >
static bool equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
 Determines whether the specified object instances are considered equal.
 
template<typename object_a_t , typename object_b_t >
static bool reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
 Determines whether the specified object instances are the same instance.
 

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::version object with the following property values.
Property 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::string version)
explicit

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>::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  major,
int32  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_exceptionmajor or minor is less than zero.
Remarks
This constructor creates a xtd::version object with the following property values.
Property 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  major,
int32  minor,
int32  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_exceptionmajor, minor or build is less than zero.
Remarks
This constructor creates a xtd::version object with the following property values.
Property 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  major,
int32  minor,
int32  build,
int32  revision 
)

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

Parameters
majorThe major version number.
minorThe minor version number.
buildThe build version number.
revisionThe revision version number.
Exceptions
xtd::out_of_range_exceptionmajor, minor, build or revision is less than zero.
Remarks
This constructor creates a xtd::version object with the following property values.
Property 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/console>
#include <xtd/startup>
#include <xtd/version>
using namespace xtd;
namespace version_example {
class program {
public:
// The main entry point for the application.
static auto main() {
auto fmt_std = "Standard version:\n"
" major.minor.build.revision = {0}.{1}.{2}.{3}";
auto fmt_int = "Interim version:\n"
" major.minor.build.maj_rev/min_rev = {0}.{1}.{2}.{3}/{4}";
auto std = version {2, 4, 1128, 2};
auto interim = version {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_(version_example::program::main);
// 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 xtd::version::build ( ) const
noexcept

Gets the value of the build component of the version number for the current xtd::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.

◆ major()

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

Gets the value of the major component of the version number for the current xtd::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 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 xtd::version::minor ( ) const
noexcept

Gets the value of the minor component of the version number for the current xtd::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 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.

◆ revision()

int32 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.

◆ compare_to()

int32 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 xtd::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 >.

◆ equals() [1/3]

bool xtd::version::equals ( const version ) const
overridevirtualnoexcept

Indicates whether the current object is equal to another object of the same type.

Parameters
objAn object to compare with this object.
Returns
true if the current object is equal to the other parameter; otherwise, false.

Implements xtd::iequatable< version >.

◆ to_string() [1/2]

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

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

Returns
The xtd::string 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::string xtd::version::to_string ( size_t  field_count) const

Converts the value of the current xtd::version object to its equivalent xtd::string 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::string 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.

◆ parse()

static version xtd::version::parse ( const xtd::string 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>::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 string&) constructor.

◆ try_parse()

static bool xtd::version::try_parse ( const xtd::string 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>::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.

◆ equals() [2/3]

virtual bool xtd::object::equals ( const object obj) const
virtualnoexcept

Determines whether the specified object is equal to the current object.

Parameters
objThe object to compare with the current object.
Returns
true if the specified object is equal to the current object. otherwise, false.
Examples
The following code example compares the current instance with another object.
#include <xtd/console>
using namespace xtd;
auto main() -> int {
auto object1 = new_ptr<object>();
auto object2 = new_ptr<object>();
auto object3 = object2;
console::write_line(object1->equals(*object3));
console::write_line(*object1 == *object3);
object3 = object1;
console::write_line(object1->equals(*object3));
console::write_line(*object1 == *object3);
}
// This code produces the following output :
//
// false
// false
// true
// true

Reimplemented from xtd::object.

◆ equals() [3/3]

template<typename object_a_t , typename object_b_t >
static bool xtd::object::equals ( const object_a_t &  object_a,
const object_b_t &  object_b 
)
inlinestaticnoexcept

Determines whether the specified object instances are considered equal.

Parameters
object_aThe first object to compare.
object_bThe second object to compare.
Returns
true if object_a is the same instance as object_b or if both are null references or if object_a(object_b) returns true. otherwise, false.
Examples
The following code example compares different objects.
#include <xtd/console>
using namespace xtd;
auto main() -> int {
string s1 = "Tom";
string s2 = "Carol";
console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
s1 = "Tom";
s2 = "Tom";
console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
s1 = "";
s2 = "Tom";
console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
s1 = "Carol";
s2 = "";
console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
s1 = "";
s2 = "";
console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
}
// This code produces the following output :
//
// object::equals("Tom", "Carol") => false
// object::equals("Tom", "Tom") => true
// object::equals("", "Tom") => false
// object::equals("Carol", "") => false
// object::equals("", "") => true
virtual bool equals(const object &obj) const noexcept
Determines whether the specified object is equal to the current object.

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