Offset
The Offset
immutable class represents a time zone offset from UTC (Coordinated Universal Time) broken down into hours and minutes. It provides a variety of methods for creation, formatting, comparison, calculation, and conversion of offset instances.
TIP
All instances of Offset
are immutable!
So all manipulation methods return a new instance of offset.
Table of Contents
Instance Properties
hour
Return the number of hours in the offset.
- Type:
number
Example:
const offset = Offset.fromObject({
hour: 1,
minute: 30,
});
console.log(offset.hour); // 1
minute
Return the number of minutes in the offset.
- Type:
number
Example:
const offset = Offset.fromObject({
hour: 1,
minute: 30,
});
console.log(offset.minute); // 30
inHours
Returns the total offset in hours.
- Type:
number
Example:
const offset = Offset.fromObject({
hour: 1,
minute: 30,
});
console.log(offset.inHours); // 1.5
inMinutes
Returns the total offset in minutes.
- Type:
number
Example:
const offset = Offset.fromObject({
hour: 1,
minute: 30,
});
console.log(offset.inMinutes); // 90
Instance Methods
valueOf
Returns the total offset in milliseconds.
valueOf(): number
- Parameters:
void
- Returns:
number
- Throws:
void
Example:
const offset = Offset.fromObject({
hour: 1,
minute: 30,
});
console.log(offset.valueOf()); // 5400000
toString
Returns the human-readable string representation of the offset.
toString(): string
- Parameters:
void
- Returns:
string
- Throws:
void
Example:
const offset = Offset.fromObject({
hour: 1,
minute: 30,
});
console.log(offset.toString()); // UTC+01:30
[Symbol.toPrimitive]
Custom implementation to handle coercion.
[Symbol.toPrimitive](hint: string): number | string
- Parameters:
hint
:- description: The hint type (
"number"
or"string"
) - Type:
string
- description: The hint type (
- Returns:
string | number
- Throws:
void
Example:
const offset = Offset.fromObject({
hour: 1,
minute: 30,
});
console.log(+offset); // 5400000
console.log(`${offset}`); // UTC+01:30
toJSON
Returns the JSON serialization representation of the offset.
toJSON(): string
- Parameters:
void
- Returns:
string
- Throws:
void
Example:
const offset = Offset.fromObject({
hour: 1,
minute: 30,
});
console.log(offset.toJSON()); // "+01:30"
toISOString
Returns the ISO 8601 representation of the offset.
toISOString(): string
- Parameters:
void
- Returns:
string
- Throws:
void
Example:
const offset = Offset.fromObject({
hour: 1,
minute: 30,
});
console.log(offset.toISOString()); // +01:30
toObject
Returns the object literal of the offset.
toObject(): Object
- Parameters:
void
- Returns:
Object
- Throws:
void
Example:
const offset = Offset.fromObject({
hour: 1,
minute: 30,
});
console.log(offset.toObject()); // {hour: 1, minute: 30}
toDuration
Returns the duration of the offset.
toDuration(): Duration
- Parameters:
void
- Returns:
Duration
- Throws:
void
Example:
const offset = Offset.fromObject({
hour: 1,
minute: 30,
});
console.log(offset.toDuration().toString()); // 01:30:00
equals
Returns whether the offset is equal to the other offset.
equals(other: Offset): boolean
- Parameters:
other
:- description: The other offset to compare against.
- Type:
Offset
- Returns:
boolean
- Throws:
void
Example:
const offset1 = Offset.fromObject({
hour: 1,
minute: 30,
});
const offset2 = Offset.fromObject({
hour: 1,
minute: 30,
});
console.log(offset1.equals(offset2)); // true
isEasterThan
Returns whether the offset is easter than the other offset.
isEasterThan(other: Offset): boolean
- Parameters:
other
:- description: The other offset to compare against.
- Type:
Offset
- Returns:
boolean
- Throws:
void
Example:
const offset1 = Offset.fromObject({
hour: 1,
minute: 30,
});
const offset2 = Offset.fromObject({
hour: 1,
minute: 30,
});
console.log(offset1.isEasterThan(offset2)); // false
isWesterThan
Returns whether the offset is wester than the other offset.
isWesterThan(other: Offset): boolean
- Parameters:
other
:- description: The other offset to compare against.
- Type:
Offset
- Returns:
boolean
- Throws:
void
Example:
const offset1 = Offset.fromObject({
hour: 1,
minute: 30,
});
const offset2 = Offset.fromObject({
hour: 1,
minute: 30,
});
console.log(offset1.isWesterThan(offset2)); // false
withHour
Return a new offset with hours replaced.
withHour(hour: number): Offset
- Parameters:
hour
:- description: The hour to replace the old one.
- Type:
number
- Returns:
Offset
- Throws:
void
Example:
const offset = Offset.fromObject({
hour: 1,
minute: 30,
});
const offsetWithHour = offset.withHour(2);
console.log(offsetWithHour.toString()); // UTC+02:30
withMinute
Return a new offset with minutes replaced.
withMinute(minute: number): Offset
- Parameters:
minute
:- description: The minute to replace the old one.
- Type:
number
- Returns:
Offset
- Throws:
void
Example:
const offset = Offset.fromObject({
hour: 1,
minute: 30,
});
const offsetWithMinute = offset.withMinute(0);
console.log(offsetWithMinute.toString()); // UTC+01:00
plus
Return a new offset as the sum of the offset with another offset.
plus(other: Offset): Offset
- Parameters:
other
:- description: The other offset to calculate the sum of.
- Type:
Offset
- Returns:
Offset
- Throws:
void
Example:
const offset1 = Offset.fromObject({
hour: 1,
minute: 30,
});
const offset2 = Offset.fromObject({
hour: 1,
});
const sum = offset1.plus(offset2);
console.log(sum.toString()); // UTC+02:30
minus
Return a new offset as the difference of the offset with another offset.
minus(other: Offset): Offset
- Parameters:
other
:- description: The other offset to calculate the difference of.
- Type:
Offset
- Returns:
Offset
- Throws:
void
Example:
const offset1 = Offset.fromObject({
hour: 1,
minute: 30,
});
const offset2 = Offset.fromObject({
hour: 1,
});
const diff = offset1.minus(offset2);
console.log(diff.toString()); // UTC+00:30
negate
Return a new offset as the negated offset.
negate(): Offset
- Parameters:
void
- Returns:
Offset
- Throws:
void
Example:
const offset = Offset.fromObject({
hour: 1,
minute: 30,
});
const negated = offset.negate();
console.log(negated.toString()); // UTC-01:30
absolute
Return a new offset as the absolute offset.
absolute(): Offset
- Parameters:
void
- Returns:
Offset
- Throws:
void
Example:
const offset = Offset.fromObject({
hour: -1,
minute: -30,
});
const abs = offset.absolute();
console.log(abs.toString()); // UTC+01:30
Static Properties
UTC
Return the offset of UTC.
- Type:
Offset
Example:
const offset = Offset.UTC;
console.log(offset.toString()); // UTC
Static Methods
fromHours
Return a new offset from the total hours.
Offset.fromHours(inHours: number): Offset
- Parameters:
inHours
:- description: the total offset in hours.
- Type:
number
- Returns:
Offset
- Throws:
void
Example:
const offset = Offset.fromHours(1.5);
console.log(offset.toString()); // UTC+01:30
fromMinutes
Return a new offset from the total minutes.
Offset.fromMinutes(inMinutes: number): Offset
- Parameters:
inMinutes
:- description: the total offset in minutes.
- Type:
number
- Returns:
Offset
- Throws:
void
Example:
const offset = Offset.fromMinutes(90);
console.log(offset.toString()); // UTC+01:30
fromObject
Return a new offset from an object literal.
Offset.fromObject(object: Object): Offset
- Parameters:
object
:- description: the object literal.
- Type:
Object
- Returns:
Offset
- Throws:
void
Example:
const offset = Offset.fromObject({
hour: 1,
minute: 30,
});
console.log(offset.toString()); // UTC+01:30
fromString
Return a new offset from a human-readable string representation.
Offset.fromString(str: string): Offset
- Parameters:
str
:- description: the human-readable string representation.
- Type:
string
- Returns:
Offset
- Throws:
void
Example:
const offset = Offset.fromString("UTC+01:30");
console.log(offset.toObject()); // {hour: 1, minute: 30}
fromISOString
Return a new offset from an ISO 8601 representation.
Offset.fromISOString(str: string): Offset
- Parameters:
str
:- description: the ISO 8601 representation.
- Type:
string
- Returns:
Offset
- Throws:
void
Example:
const offset = Offset.fromISOString("+01:30");
console.log(offset.toObject()); // {hour: 1, minute: 30}
parse
Return a new offset from any possible string.
Offset.parse(str: string): Offset
- Parameters:
str
:- description: the string.
- Type:
string
- Returns:
Offset
- Throws:
void
Example:
const offset = Offset.parse("UTC+01:30");
console.log(offset.toObject()); // {hour: 1, minute: 30}
fromDuration
Return a new offset from a duration.
Offset.fromDuration(duration: Duration): Offset
- Parameters:
duration
:- description: the duration.
- Type:
Duration
- Returns:
Offset
- Throws:
void
Example:
const duration = Duration.fromObject({
hour: 1,
minute: 30,
});
const offset = Offset.fromDuration(duration);
console.log(offset.toString()); // UTC+01:30
fromZoneName
Return a new offset from a zone name.
Offset.fromZoneName(zoneName: string): Offset
- Parameters:
zoneName
:- description: the zone name.
- Type:
string
- Returns:
Offset
- Throws:
void
Example:
const offset = Offset.fromZoneName("America/New_York");
console.log(offset.toObject()); // {hour: -5, minute: 0}
local
Return the local offset.
Offset.local(): Offset
- Parameters:
void
- Returns:
Offset
- Throws:
void
Example:
const offset = Offset.local();
console.log(offset.toString()); // depends on your zone
compare
Returns the difference between two offsets.
TIP
This method is useful for sorting Offset
instances in an array.
Offset.compare(offset1: Offset, offset2: Offset): number
- Parameters:
offset1
:- description: The first offset.
- Type:
Offset
offset2
:- description: The second offset.
- Type:
Offset
- Returns:
number
- Throws:
void
Example:
const offset1 = Offset.fromObject({
hour: 1,
minute: 30,
});
const offset2 = Offset.fromObject({
hour: 1,
minute: 30,
});
console.log(Offset.compare(offset1, offset2)); // 0