Struct Offset

An offset from UTC in seconds. A positive value means that the local time is ahead of UTC (e.g. for Europe); a negative value means that the local time is behind UTC (e.g. for America).

Since 1.0.x

Availability net6.0, netstandard2.0

Implements

IEquatable<Offset>

IComparable<Offset>

IFormattable

IComparable

IXmlSerializable

Inherited Members

Object.Equals(Object, Object)

Object.GetType()

Object.ReferenceEquals(Object, Object)

Namespace: NodaTime

Assembly: NodaTime.dll

Syntax

[TypeConverter(typeof(OffsetTypeConverter))]
public readonly struct Offset : IEquatable<Offset>, IComparable<Offset>, IFormattable, IComparable, IXmlSerializable

Remarks

Offsets are always in the range of [-18, +18] hours. (Note that the ends are inclusive, so an offset of 18 hours can be represented, but an offset of 18 hours and one second cannot.) This allows all offsets within TZDB to be represented. The BCL System.DateTimeOffset type only allows offsets up to 14 hours, which means some historical data within TZDB could not be represented.

Offsets are represented with a granularity of one second. This allows all offsets within TZDB to be represented. It is possible that it could present issues to some other time zone data sources, but only in very rare historical cases (or fictional ones).

Equality and ordering are defined in the natural way by comparing the underlying number of seconds. For example, this means that offsets for America are ordered before offsets in Europe.

Fields

MaxValue

The maximum permitted offset; 18 hours after UTC.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public static readonly Offset MaxValue

Field Value

Type	Description
Offset

MinValue

The minimum permitted offset; 18 hours before UTC.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public static readonly Offset MinValue

Field Value

Type	Description
Offset

Zero

An offset of zero seconds - effectively the permanent offset for UTC.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public static readonly Offset Zero

Field Value

Type	Description
Offset

Properties

Milliseconds

Gets the number of milliseconds represented by this offset, which may be negative.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public readonly int Milliseconds { get; }

Property Value

Type	Description
Int32	The number of milliseconds represented by this offset, which may be negative.

Remarks

Offsets are only accurate to second precision; the number of seconds is simply multiplied by 1,000 to give the number of milliseconds.

Nanoseconds

Gets the number of nanoseconds represented by this offset, which may be negative.

Since 2.0.x

Availability net6.0, netstandard2.0

Declaration

public readonly long Nanoseconds { get; }

Property Value

Type	Description
Int64	The number of nanoseconds.

Remarks

Offsets are only accurate to second precision; the number of seconds is simply multiplied by 1,000,000,000 to give the number of nanoseconds.

Seconds

Gets the number of seconds represented by this offset, which may be negative.

Since 2.0.x

Availability net6.0, netstandard2.0

Declaration

public readonly int Seconds { get; }

Property Value

Type	Description
Int32	The number of seconds represented by this offset, which may be negative.

Ticks

Gets the number of ticks represented by this offset, which may be negative.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public readonly long Ticks { get; }

Property Value

Type	Description
Int64	The number of ticks.

Remarks

Offsets are only accurate to second precision; the number of seconds is simply multiplied by 10,000,000 to give the number of ticks.

Methods

Add(Offset, Offset)

Adds one Offset to another. Friendly alternative to operator+().

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public static Offset Add(Offset left, Offset right)

Parameters

Type	Name	Description
Offset	left	The left hand side of the operator.
Offset	right	The right hand side of the operator.

Returns

Type	Description
Offset	A new Offset representing the sum of the given values.

Sample snippet

using NodaTime;
using System;

var leftHandOffset = Offset.FromHours(5);
var rightHandOffset = Offset.FromHours(6);
var result = Offset.Add(leftHandOffset, rightHandOffset);
Console.WriteLine(result);

Output:

+11

Exceptions

Type	Condition
ArgumentOutOfRangeException	The result of the operation is outside the range of Offset.
ArgumentOutOfRangeException	The result of the operation is outside the range of Offset.

AddSchema(XmlSchemaSet)

Adds the XML schema type describing the structure of the Offset XML serialization to the given xmlSchemaSet.

Since 3.0.x

Availability net6.0, netstandard2.0

Declaration

public static XmlQualifiedName AddSchema(XmlSchemaSet xmlSchemaSet)

Parameters

Type	Name	Description
XmlSchemaSet	xmlSchemaSet	The XML schema set provided by System.Xml.Serialization.XmlSchemaExporter.

Returns

Type	Description
XmlQualifiedName	The qualified name of the schema type that was added to the xmlSchemaSet.

CompareTo(Offset)

Compares the current object with another object of the same type. See the type documentation for a description of ordering semantics.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public readonly int CompareTo(Offset other)

Parameters

Type	Name	Description
Offset	other	An object to compare with this object.

Returns

Type	Description
Int32	A 32-bit signed integer that indicates the relative order of the objects being compared. The return value has the following meanings: Value Meaning < 0 This object is less than the other parameter. 0 This object is equal to other. > 0 This object is greater than other.

Sample snippet

using NodaTime;
using System;

var smallerOffset = Offset.FromHours(3);
var largerOffset = Offset.FromHours(5);

var lessThan = smallerOffset.CompareTo(largerOffset);
var equal = smallerOffset.CompareTo(smallerOffset);
var greaterThan = largerOffset.CompareTo(smallerOffset);

Console.WriteLine(lessThan);
Console.WriteLine(equal);
Console.WriteLine(greaterThan);

Output:

-1
0
1

Equals(Offset)

Indicates whether the current object is equal to another object of the same type. See the type documentation for a description of equality semantics.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public readonly bool Equals(Offset other)

Parameters

Type	Name	Description
Offset	other	An object to compare with this object.

Returns

Type	Description
Boolean	true if the current object is equal to the other parameter; otherwise, false.

Sample snippet

using NodaTime;
using System;

var offset1 = Offset.FromHoursAndMinutes(1, 30);
var inequalOffset = Offset.FromHours(2);

var unequal = offset1.Equals(inequalOffset);
var equal = offset1.Equals(offset1);

Console.WriteLine(unequal);
Console.WriteLine(equal);

Output:

False
True

Equals(Object)

Determines whether the specified System.Object is equal to this instance. See the type documentation for a description of equality semantics.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public override readonly bool Equals(object obj)

Parameters

Type	Name	Description
Object	obj	The System.Object to compare with this instance.

Returns

Type	Description
Boolean	true if the specified System.Object is equal to this instance; otherwise, false.

Overrides

System.ValueType.Equals(System.Object)

FromHours(Int32)

Returns an offset for the specified number of hours, which may be negative.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public static Offset FromHours(int hours)

Parameters

Type	Name	Description
Int32	hours	The number of hours to represent in the new offset.

Returns

Type	Description
Offset	An offset representing the given value.

Sample snippet

using NodaTime;
using System;

Offset offset = Offset.FromHours(1);
Console.WriteLine(offset.Seconds);

Output:

3600

Exceptions

Type	Condition
ArgumentOutOfRangeException	The specified number of hours is outside the range of [-18, +18].

FromHoursAndMinutes(Int32, Int32)

Returns an offset for the specified number of hours and minutes.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public static Offset FromHoursAndMinutes(int hours, int minutes)

Parameters

Type	Name	Description
Int32	hours	The number of hours to represent in the new offset.
Int32	minutes	The number of minutes to represent in the new offset.

Returns

Type	Description
Offset	An offset representing the given value.

Remarks

The result simply takes the hours and minutes and converts each component into milliseconds separately. As a result, a negative offset should usually be obtained by making both arguments negative. For example, to obtain "three hours and ten minutes behind UTC" you might call Offset.FromHoursAndMinutes(-3, -10).

Sample snippet

using NodaTime;
using System;

Offset offset = Offset.FromHoursAndMinutes(1, 1);
Console.WriteLine(offset.Seconds);

Output:

3660

Exceptions

Type	Condition
ArgumentOutOfRangeException	The result of the operation is outside the range of Offset.

FromMilliseconds(Int32)

Returns an offset for the given milliseconds value, which may be negative.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public static Offset FromMilliseconds(int milliseconds)

Parameters

Type	Name	Description
Int32	milliseconds	The int milliseconds value.

Returns

Type	Description
Offset	An offset representing the given number of milliseconds, to the (truncated) second.

Remarks

Offsets are only accurate to second precision; the given number of milliseconds is simply divided by 1,000 to give the number of seconds - any remainder is truncated.

Sample snippet

using NodaTime;
using System;

Offset offset = Offset.FromMilliseconds(1200);
Console.WriteLine(offset.Seconds);
Console.WriteLine(offset.Milliseconds);

Output:

1
1000

Exceptions

Type	Condition
ArgumentOutOfRangeException	The specified number of milliseconds is outside the range of [-18, +18] hours.

FromNanoseconds(Int64)

Returns an offset for the given number of nanoseconds, which may be negative.

Since 2.0.x

Availability net6.0, netstandard2.0

Declaration

public static Offset FromNanoseconds(long nanoseconds)

Parameters

Type	Name	Description
Int64	nanoseconds	The number of nanoseconds specifying the length of the new offset.

Returns

Type	Description
Offset	An offset representing the given number of nanoseconds, to the (truncated) second.

Remarks

Offsets are only accurate to second precision; the given number of nanoseconds is simply divided by 1,000,000,000 to give the number of seconds - any remainder is truncated towards zero.

Sample snippet

using NodaTime;
using System;

Offset offset = Offset.FromNanoseconds(1_200_000_000);
Console.WriteLine(offset.Seconds);
Console.WriteLine(offset.Nanoseconds);

Output:

1
1000000000

Exceptions

Type	Condition
ArgumentOutOfRangeException	The specified number of nanoseconds is outside the range of [-18, +18] hours.

FromSeconds(Int32)

Returns an offset for the given seconds value, which may be negative.

Since 2.0.x

Availability net6.0, netstandard2.0

Declaration

public static Offset FromSeconds(int seconds)

Parameters

Type	Name	Description
Int32	seconds	The int seconds value.

Returns

Type	Description
Offset	An offset representing the given number of seconds.

Sample snippet

using NodaTime;
using System;

Offset offset = Offset.FromSeconds(450);
Console.WriteLine(offset.Seconds);

Output:

450

Exceptions

Type	Condition
ArgumentOutOfRangeException	The specified number of seconds is outside the range of [-18, +18] hours.

FromTicks(Int64)

Returns an offset for the given number of ticks, which may be negative.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public static Offset FromTicks(long ticks)

Parameters

Type	Name	Description
Int64	ticks	The number of ticks specifying the length of the new offset.

Returns

Type	Description
Offset	An offset representing the given number of ticks, to the (truncated) second.

Remarks

Offsets are only accurate to second precision; the given number of ticks is simply divided by 10,000,000 to give the number of seconds - any remainder is truncated.

Sample snippet

using NodaTime;
using System;

Offset offset = Offset.FromTicks(15_000_000);
Console.WriteLine(offset.Ticks);
Console.WriteLine(offset.Seconds);

Output:

10000000
1

Exceptions

Type	Condition
ArgumentOutOfRangeException	The specified number of ticks is outside the range of [-18, +18] hours.

FromTimeSpan(TimeSpan)

Converts the given System.TimeSpan to an offset, with fractional seconds truncated.

Since 2.0.x

Availability net6.0, netstandard2.0

Declaration

public static Offset FromTimeSpan(TimeSpan timeSpan)

Parameters

Type	Name	Description
TimeSpan	timeSpan	The timespan to convert

Returns

Type	Description
Offset	An offset for the same time as the given time span.

Sample snippet

using NodaTime;
using System;

var timespan = TimeSpan.FromHours(1.5);
Offset offset = Offset.FromTimeSpan(timespan);
Console.WriteLine(offset.Seconds);

Output:

5400

Exceptions

Type	Condition
ArgumentOutOfRangeException	The given time span falls outside the range of +/- 18 hours.

GetHashCode()

Returns a hash code for this instance. See the type documentation for a description of equality semantics.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public override readonly int GetHashCode()

Returns

Type	Description
Int32	A hash code for this instance, suitable for use in hashing algorithms and data structures like a hash table.

Overrides

System.ValueType.GetHashCode()

Max(Offset, Offset)

Returns the greater offset of the given two, i.e. the one which will give a later local time when added to an instant.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public static Offset Max(Offset x, Offset y)

Parameters

Type	Name	Description
Offset	x	The first offset
Offset	y	The second offset

Returns

Type	Description
Offset	The greater offset of x and y.

Sample snippet

using NodaTime;
using System;

var smallerOffset = Offset.FromHours(3);
var largerOffset = Offset.FromHours(5);
var result = Offset.Max(smallerOffset, largerOffset);
Console.WriteLine(result);

Output:

+05

Min(Offset, Offset)

Returns the lower offset of the given two, i.e. the one which will give an earlier local time when added to an instant.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public static Offset Min(Offset x, Offset y)

Parameters

Type	Name	Description
Offset	x	The first offset
Offset	y	The second offset

Returns

Type	Description
Offset	The lower offset of x and y.

Sample snippet

using NodaTime;
using System;

var smallerOffset = Offset.FromHours(3);
var largerOffset = Offset.FromHours(5);
var result = Offset.Min(smallerOffset, largerOffset);
Console.WriteLine(result);

Output:

+03

Minus(Offset)

Returns the result of subtracting another Offset from this one, for a fluent alternative to operator-().

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public readonly Offset Minus(Offset other)

Parameters

Type	Name	Description
Offset	other	The offset to subtract

Returns

Type	Description
Offset	The result of subtracting the other offset from this one.

Sample snippet

using NodaTime;
using System;

var offset = Offset.FromSeconds(100);
var offset2 = Offset.FromSeconds(120);
var expected = Offset.FromSeconds(-20);
var actual = offset.Minus(offset2);

Console.WriteLine(actual);

Output:

-00:00:20

Exceptions

Type	Condition
ArgumentOutOfRangeException	The result of the operation is outside the range of Offset.

Negate(Offset)

Returns the negation of the specified offset. This is the method form of the unary minus operator.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public static Offset Negate(Offset offset)

Parameters

Type	Name	Description
Offset	offset	The offset to negate.

Returns

Type	Description
Offset	The negation of the specified offset.

Sample snippet

using NodaTime;
using System;

var offsetToNegate = Offset.FromHours(2);
var result = Offset.Negate(offsetToNegate);
Console.WriteLine(result);

Output:

-02

Plus(Offset)

Returns the result of adding another Offset to this one, for a fluent alternative to operator+().

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public readonly Offset Plus(Offset other)

Parameters

Type	Name	Description
Offset	other	The offset to add

Returns

Type	Description
Offset	The result of adding the other offset to this one.

Sample snippet

using NodaTime;
using System;

var offset = Offset.FromSeconds(100);
var offset2 = Offset.FromSeconds(150);
var expected = Offset.FromSeconds(250);
var actual = offset.Plus(offset2);

Console.WriteLine(actual);

Output:

+00:04:10

Exceptions

Type	Condition
ArgumentOutOfRangeException	The result of the operation is outside the range of Offset.

Subtract(Offset, Offset)

Subtracts one Offset from another. Friendly alternative to operator-().

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public static Offset Subtract(Offset minuend, Offset subtrahend)

Parameters

Type	Name	Description
Offset	minuend	The left hand side of the operator.
Offset	subtrahend	The right hand side of the operator.

Returns

Type	Description
Offset	A new Offset representing the difference of the given values.

Sample snippet

using NodaTime;
using System;

var leftHandOffset = Offset.FromHours(7);
var rightHandOffset = Offset.FromHours(5);
var result = Offset.Subtract(leftHandOffset, rightHandOffset);
Console.WriteLine(result);

Output:

+02

Exceptions

Type	Condition
ArgumentOutOfRangeException	The result of the operation is outside the range of Offset.
ArgumentOutOfRangeException	The result of the operation is outside the range of Offset.

ToString()

Returns a System.String that represents this instance.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public override readonly string ToString()

Returns

Type	Description
String	The value of the current instance in the default format pattern ("g"), using the current thread's culture to obtain a format provider.

Overrides

System.ValueType.ToString()

ToString(String, IFormatProvider)

Formats the value of the current instance using the specified pattern.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public readonly string ToString(string patternText, IFormatProvider formatProvider)

Parameters

Type	Name	Description
String	patternText	The System.String specifying the pattern to use, or null to use the default format pattern ("g").
IFormatProvider	formatProvider	The System.IFormatProvider to use when formatting the value, or null to use the current thread's culture to obtain a format provider.

Returns

Type	Description
String	A System.String containing the value of the current instance in the specified format.

ToTimeSpan()

Converts this offset to a .NET standard System.TimeSpan value.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public readonly TimeSpan ToTimeSpan()

Returns

Type	Description
TimeSpan	An equivalent System.TimeSpan to this value.

Sample snippet

using NodaTime;
using System;

var offset = Offset.FromSeconds(120);
var actual = offset.ToTimeSpan();
var expected = TimeSpan.FromSeconds(120);

Console.WriteLine(actual);

Output:

00:02:00

Operators

Addition(Offset, Offset)

Implements the operator + (addition).

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public static Offset operator +(Offset left, Offset right)

Parameters

Type	Name	Description
Offset	left	The left hand side of the operator.
Offset	right	The right hand side of the operator.

Returns

Type	Description
Offset	A new Offset representing the sum of the given values.

Exceptions

Type	Condition
ArgumentOutOfRangeException	The result of the operation is outside the range of Offset.
ArgumentOutOfRangeException	The result of the operation is outside the range of Offset.

Equality(Offset, Offset)

Implements the operator == (equality). See the type documentation for a description of equality semantics.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public static bool operator ==(Offset left, Offset right)

Parameters

Type	Name	Description
Offset	left	The left hand side of the operator.
Offset	right	The right hand side of the operator.

Returns

Type	Description
Boolean	true if values are equal to each other, otherwise false.

GreaterThan(Offset, Offset)

Implements the operator > (greater than). See the type documentation for a description of ordering semantics.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public static bool operator>(Offset left, Offset right)

Parameters

Type	Name	Description
Offset	left	The left hand side of the operator.
Offset	right	The right hand side of the operator.

Returns

Type	Description
Boolean	true if the left value is greater than the right value, otherwise false.

GreaterThanOrEqual(Offset, Offset)

Implements the operator >= (greater than or equal). See the type documentation for a description of ordering semantics.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public static bool operator >=(Offset left, Offset right)

Parameters

Type	Name	Description
Offset	left	The left hand side of the operator.
Offset	right	The right hand side of the operator.

Returns

Type	Description
Boolean	true if the left value is greater than or equal to the right value, otherwise false.

Inequality(Offset, Offset)

Implements the operator != (inequality). See the type documentation for a description of equality semantics.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public static bool operator !=(Offset left, Offset right)

Parameters

Type	Name	Description
Offset	left	The left hand side of the operator.
Offset	right	The right hand side of the operator.

Returns

Type	Description
Boolean	true if values are not equal to each other, otherwise false.

LessThan(Offset, Offset)

Implements the operator < (less than). See the type documentation for a description of ordering semantics.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public static bool operator <(Offset left, Offset right)

Parameters

Type	Name	Description
Offset	left	The left hand side of the operator.
Offset	right	The right hand side of the operator.

Returns

Type	Description
Boolean	true if the left value is less than the right value, otherwise false.

LessThanOrEqual(Offset, Offset)

Implements the operator <= (less than or equal). See the type documentation for a description of ordering semantics.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public static bool operator <=(Offset left, Offset right)

Parameters

Type	Name	Description
Offset	left	The left hand side of the operator.
Offset	right	The right hand side of the operator.

Returns

Type	Description
Boolean	true if the left value is less than or equal to the right value, otherwise false.

Subtraction(Offset, Offset)

Implements the operator - (subtraction).

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public static Offset operator -(Offset minuend, Offset subtrahend)

Parameters

Type	Name	Description
Offset	minuend	The left hand side of the operator.
Offset	subtrahend	The right hand side of the operator.

Returns

Type	Description
Offset	A new Offset representing the difference of the given values.

Exceptions

Type	Condition
ArgumentOutOfRangeException	The result of the operation is outside the range of Offset.
ArgumentOutOfRangeException	The result of the operation is outside the range of Offset.

UnaryNegation(Offset)

Implements the unary operator - (negation).

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public static Offset operator -(Offset offset)

Parameters

Type	Name	Description
Offset	offset	The offset to negate.

Returns

Type	Description
Offset	A new Offset instance with a negated value.

UnaryPlus(Offset)

Implements the unary operator + .

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public static Offset operator +(Offset offset)

Parameters

Type	Name	Description
Offset	offset	The operand.

Returns

Type	Description
Offset	The same Offset instance

Remarks

There is no method form of this operator; the Plus(Offset) method is an instance method for addition, and is more useful than a method form of this would be.

Explicit Interface Implementations

IComparable.CompareTo(Object)

Implementation of System.IComparable.CompareTo(System.Object) to compare two offsets. See the type documentation for a description of ordering semantics.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

readonly int IComparable.CompareTo(object obj)

Parameters

Type	Name	Description
Object	obj	The object to compare this value with.

Returns

Type	Description
Int32	The result of comparing this instant with another one; see CompareTo(Offset) for general details. If obj is null, this method returns a value greater than 0.

Remarks

This uses explicit interface implementation to avoid it being called accidentally. The generic implementation should usually be preferred.

Exceptions

Type	Condition
ArgumentException	obj is non-null but does not refer to an instance of Offset.

IXmlSerializable.ReadXml(XmlReader)

Since 1.2.x

Availability net6.0, netstandard2.0

Declaration

readonly void IXmlSerializable.ReadXml(XmlReader reader)

Parameters

Type	Name	Description
XmlReader	reader

IXmlSerializable.WriteXml(XmlWriter)

Since 1.2.x

Availability net6.0, netstandard2.0

Declaration

readonly void IXmlSerializable.WriteXml(XmlWriter writer)

Parameters

Type	Name	Description
XmlWriter	writer

Implements

System.IEquatable<T>

System.IComparable<T>

System.IFormattable

System.IComparable

System.Xml.Serialization.IXmlSerializable