RingoJS

RINGO JS 1.2.1

模块 ringo/utils/dates

添加用于处理 JavaScript Date 对象的有用函数。

Example

var dates = require("ringo/utils/dates");
var now = new Date(2016, 0, 1);
var y2k = new Date(2000, 0, 1);

dates.after(now, y2k); // --> true
dates.before(now, y2k); // --> false
dates.isLeapYear(y2k); // --> true
dates.weekOfYear(y2k); // --> 52 (1st week starts at 3rd)
dates.yearInCentury(y2k); // --> 0
dates.diff(y2k, now); // --> 5844
dates.diff(y2k, now, "mixed"); // { days: 5844, hours: 0, ... }

Functions

add (date, delta, unit)

如果增量为负数，则将 delta 增加到给定字段或将其减少。 如果更大的领域有效，他们将相应地改变。

Example

var d1 = new Date(Date.UTC(2016, 0, 1, 0, 0));
var d2 = dates.add(d1, 1, "hour");
dates.diff(d1, d2, "hours"); // --> 1

Parameters

Date date

base date to add or remove time from.
Number delta

amount of time to add (positive delta) or remove (negative delta).
String unit

(optional) field to change. Possible values: year, quarter, month, week, day (default), hour (24-hour clock), minute, second, millisecond, and their respective plural form.

Returns

Date

date with the calculated date and time

after (a, b)

检查data a是否在data b之后。 这等于 compare(a, b) > 0

Parameters

Date a

first date
Date b

second date

Returns

Boolean

true if a is after b, false if not.

before (a, b)

检查data a 是否在data b之前 。 这等于 compareTo(a, b) < 0

Parameters

Date a

first date
Date b

second date

Returns

Boolean

true if a is before b, false if not.

checkDate (fullYear, month, day)

检查data是否有效。

Example

// 2007 is no leap year, so no 29th February
dates.checkDate(2007, 1, 29); // --> false

Parameters

Number fullYear
Number month

between 0 and 11
Number day

between 1 and 31

Returns

Boolean

true, if the date is valid, false if not.

compare (a, b)

比较 a 和 b 的时间值。

Parameters

Date a

first date
Date b

second date

Returns

Number

-1 if a is before b, 0 if equals and 1 if a is after b.

dayOfYear (date)

获取给定data是一年中的哪一天。

Parameters

Date date

calculate the day of the year.

Returns

Number

day of the year

daysInFebruary (date)

获取二月份的天数。

Parameters

Date date

of year to find the number of days in february.

Returns

Number

days in the february, 28 or 29, if it's a leap year.

daysInMonth (date)

获取当月的天数。

Parameters

Date date

to find the maximum number of days.

Returns

Number

days in the month, between 28 and 31.

daysInYear (date)

获取当年的天数。

Parameters

Date date

to find the maximum number of days.

Returns

Number

days in the year, 365 or 366, if it's a leap year.

diff (a, b, unit)

获取以时间单位指定的两个日期之间的差异。

Example

var d1 = new Date(Date.UTC(2016, 0, 1, 0, 0));
var d2 = new Date(Date.UTC(2017, 0, 1));
dates.diff(d1, d2, "years"); // --> 1
dates.diff(d1, d2, "year"); // --> 1
dates.diff(d1, d2, "minutes"); // --> 527040
dates.diff(d1, d2, "mixed"); // --> { days: 366, hours: 0, … }

Parameters

Date a

first date
Date b

second date
String unit

(optional) of time to return. Possible values: year, quarter, month, week, day (default), hour, minute, second, millisecond and mixed (returns an object); and their respective plural form.

Returns

Number|Object<days, hours, minutes, seconds, milliseconds>

difference between the given dates in the specified unit of time.

firstDayOfWeek (locale)

获取一周中的第一天。

Parameters

String|java.util.Locale locale

(optional) the locale as java Locale object or lowercase two-letter ISO-639 code (e.g. "en")

Returns

Number

the first day of the week; 1 = Sunday, 2 = Monday.

format (date, format, locale, timezone)

以区域设置敏感的方式将日期格式化为字符串。有关格式模式的详细信息，请参阅 java.text.SimpleDateFormat 。

Example

var y2k = new Date(Date.UTC(2000, 0, 1));
// "year 2000"
dates.format(y2k, "'year' yyyy");
// "Samstag, Januar 1, '00"
dates.format(y2k, "EEEE, MMMM d, ''yy", "de");
// "1999-12-31"
dates.format(y2k, "yyyy-MM-dd", "de", "GMT-1");
// "2000-01-01 00:00:00 GMT-00:00"
dates.format(y2k, "yyyy-MM-dd HH:mm:ss z", "de", "GMT-0");
// "1999-12-31 14:00:00 GMT-10:00"
dates.format(y2k, "yyyy-MM-dd HH:mm:ss z", "de", "GMT-10");

Parameters

Date date

the Date to format
String format

the format pattern
String|java.util.Locale locale

(optional) the locale as java Locale object or lowercase two-letter ISO-639 code (e.g. "en")
String|java.util.TimeZone timezone

(optional) the timezone as java TimeZone object or an abbreviation such as "PST", a full name such as "America/Los_Angeles", or a custom ID such as "GMT-8:00". If the id is not provided, the default timezone is used. If the timezone id is provided but cannot be understood, the "GMT" timezone is used.

Returns

String

the formatted Date

fromUTCDate (year, month, date, hour, minute, second, millisecond)

从UTC时间戳创建新的日期。这是新 new Date(Date.UTC(…)); 的替代方法;

Parameters

Number year
Number month
Number date
Number hour

(optional, default 0)
Number minute

(optional, default 0)
Number second

(optional, default 0)
Number millisecond

(optional, default 0)

Returns

Date

inPeriod (date, periodStart, periodEnd, periodStartOpen, periodEndOpen)

查看日期是否在期间，使用 periodStart <= date <= periodEnd。

Parameters

Date date

to check, if it's in the period
Date periodStart

the period's start
Date periodEnd

the period's end
Boolean periodStartOpen

start point is open - default false.
Boolean periodEndOpen

end point is open - default false.

Returns

Boolean

true if the date is in the period, false if not.

isLeapYear (date)

检查日期的年份是否为闰年。

Parameters

Date date

to check year

Returns

Boolean

true if the year is a leap year, false if not.

overlapping (aStart, aEnd, bStart, bEnd)

看看两个时期是否相互重叠。

Parameters

Date aStart

first period's start
Date aEnd

first period's end
Date bStart

second period's start
Date bEnd

second period's end

Returns

Boolean

true if the periods are overlapping at some point, false if not.

parse (str, format, locale, timezone, lenient)

使用 Java SimpleDateFormat 中的日期和时间模式将字符串解析为日期。如果没有提供格式，默认情况下，Internet 上的时间戳将遵循RFC 3339。解析器使用宽松解析将模式与字符串进行匹配：即使输入不严格地以模式形式存在，但可以使用启发式进行解析，那么解析成功。

Example

// parses input string as local time:
// Wed Jun 29 2016 12:11:10 GMT+0200 (MESZ)
let pattern = "yyyy-MM-dd'T'HH:mm:ss.SSS";
dates.parse("2016-06-29T12:11:10.001", pattern);

// enforces UTC on the input date string
// Wed Jun 29 2016 14:11:10 GMT+0200 (MESZ)
dates.parse("2016-06-29T12:11:10.001", pattern, "en", "UTC");

// accepting month names in German
dates.parse("29. Juni 2016", "dd. MMM yyyy", "de", "UTC");

// Fri Jan 01 2016 01:00:00 GMT+0100 (MEZ)
dates.parse("2016");

// Sat Aug 06 2016 02:00:00 GMT+0200 (MESZ)
dates.parse("2016-08-06");

// Sun Aug 07 2016 00:04:30 GMT+0200 (MESZ)
dates.parse("2016-08-06T22:04:30Z");

// Sun Aug 07 2016 00:04:30 GMT+0200 (MESZ)
dates.parse("2016-08-06T16:04:30-06");

Parameters

String str

The date string.
String format

(optional) a specific format pattern for the parser
String|java.util.Locale locale

(optional) the locale as java.util.Locale object or an ISO-639 alpha-2 code (e.g. "en", "de") as string
String|java.util.TimeZone timezone

(optional) the timezone as java TimeZone object or an abbreviation such as "PST", a full name such as "America/Los_Angeles", or a custom ID such as "GMT-8:00". If the id is not provided, the default timezone is used. If the timezone id is provided but cannot be understood, the "GMT" timezone is used.
Boolean lenient

(optional) disables lenient parsing if set to false.

Returns

Date|NaN

a date representing the given string, or NaN for unrecognizable strings

quarterInFiscalYear (date, fiscalYearStart)

获得财政年度的季度。

Example

// Farmers (grassland calendar starts with 1st May)
// returns 4th quarter
dates.quarterInFiscalYear(new Date(2016, 3, 30), new Date(0, 4, 1));

Parameters

Date date

to calculate the quarter for.
Date fiscalYearStart

first day in the fiscal year, default is the start of the current year

Returns

Number

quarter of the year, between 1 and 4.

quarterInYear (date)

获得一年中的季度。

Parameters

Date date

to calculate the quarter for.

Returns

Number

quarter of the year, between 1 and 4.

resetDate (date)

删除日期值，只保留小时，分钟，秒和毫秒。

Example

var d = new Date(2016, 5, 10, 10, 20, 30);

// Thu Jan 01 1970 10:20:30 GMT+0100 (MEZ)
dates.resetDate(d);

Parameters

Date date

to reset

Returns

Date

date with the original time values and 1970-01-01 as date.

resetTime (date)

将时间值重置为 0，只保留年，月和日。

Example

var d = new Date(2016, 5, 10, 10, 20, 30);

// Fri Jun 10 2016 00:00:00 GMT+0200 (MESZ)
dates.resetTime(d);

Parameters

Date date

to reset

Returns

Date

date without any time values

secondOfDay (date)

获取给定日期的第二天。

Parameters

Date date

calculate the second of the day.

Returns

Number

second of the day

toISOString (date, withTime, withTimeZone, withSeconds, withMilliseconds)

从日期创建一个 ISO 8601 兼容字符串。注意：这与 Date.toISOString() 非常相似，它只返回一个没有本地时区的基于 UTC 的字符串。如果你不需要时区，Date.toISOString() 将是更好的选择。

Example

// "2015-11-27T17:52:12+01:00"
dates.toISOString(new Date());

Parameters

Date date

to format
Boolean withTime

if true, the string will contain the time, if false only the date. Default is true.
Boolean withTimeZone

if true, the string will be in local time, if false it's in UTC. Default is true.
Boolean withSeconds

if true, the string will contain also the seconds of the date. Default true.
Boolean withMilliseconds

if true, the string will contain also the milliseconds of the date. Default false.

Returns

String

date as ISO 8601 string.

weekOfMonth (date, locale)

获取给定日期的月份的星期。

Parameters

Date date

calculate the week of the month.
String|java.util.Locale locale

(optional) the locale as java Locale object or lowercase two-letter ISO-639 code (e.g. "en")

Returns

Number

week of the month

weekOfYear (date, locale)

获取给定日期的一年的一周。

Parameters

Date date

calculate the week of the year.
String|java.util.Locale locale

(optional) the locale as java Locale object or lowercase two-letter ISO-639 code (e.g. "en")

Returns

Number

week of the year

yearInCentury (date)

获取给定日期的世纪年。

Example

dates.yearInCentury(new Date(1900, 0, 1)); // --> 0
dates.yearInCentury(new Date(2016, 0, 1)); // --> 16

Parameters

Date date

calculate the year of the century.

Returns

Number

second of the day