Aeg ja kuupäev

JavaScriptis on kõik kuupäevade ning aegadega seotud funktsioonid kogutud ühte objekti Date. Konstruktorfunktsiooni Date() on võimalik kasutada nii Date objekti loomiseks, kui ka tavafunktsioonina (sellisel juhul on tagastusväärtuseks hetke aeg stringi kujul). Samuti eksisteerivad mõned staatilised funktsioonid, mis kuuluvad vaid konstruktori enda juurde, mitte sellest tuletatud objektidele. Viimase näiteks oleks funktsioon Date.parse() tekstilisel kujul oleva ajastringi teisendamiseks ajaobjektiks.

Vastavalt standardile peab JavaScripti Date objekt olema võimeline esitama iga kuupäeva ja kellaaega millisekundi täpsusega 100 miljonit päeva enne ja peale 1. jaanuarit 1970. See tähendab umbkaudu +/- 273 785 aastat. Võrdluseks laialtlevinud Unix/POSIX timestamp loendur mis enamustes süsteemides on 32 bitine, ammendub juba 19. jaanuaril 2038.

Ajatempel kujutab endast täisarvulist numbrit, mis tähistab kindlat aega. Selline numbriline kuju teeb erinevad arvutused aegadega suhteliselt lihtsaks. Kui näiteks keeltes PHP või Python on ajatempel kujul Unix/POSIX timestamp tähistades sekundite arvu alates 1. jaanuarist 1970, siis JavaScripti ajatempel loeb samast hetkest hoopis millisekundeid.

Thu Jun 04 2009 20:35:16 GMT+0300 (EEST)
Unix/POSIX: 1244136916
JavaScript: 1244136916000

Tänu numbrilisele kujule on suhteliselt kerge leida kuupäevi alates- või enne mingit kindlat aega. Näiteks tänasest 30 päeva pärast oleva kuupäeva leiab järgnevalt.

var d = new Date(new Date().getTime() + 1000*3600*24*30);

Arvutus 1000*3600*24*30 tähendab 30 päeva millisekundites ning täpsemalt oleks see 1000 millisekundit * 3600 sekundit (1 tund) * 24 tundi (1 päev) * 30 päeva.

Konstruktorfunktsiooni Date() saab operaatoriga new käivitada neljal erineval viisil. Kõikidel juhtudel on tulemuseks Date objekt, mis sisaldab mingit kindlat, konstruktorfunktsiooni sisendparameetritest sõltuvat aega. Objekti meetodite abil on siis võimalik selle saadud ajaväärtusega manipuleerida, tagastada ainult osa kuupäevast vms.

new Date();
new Date(ajatempel);
new Date(aeg_teksti_kujul);
new Date(aasta, kuu [, päev, tund, minut, sekund, ms]);

Juhul kui parameetrit pole määratud, saab loodava objekti ajaväärtuseks objekti loomise aeg. Ajatempel sisendina tähendab millisekundeid alates 1. jaanuar 1970. Aeg teksti kujul peab olema JavaScripti jaoks arusaadaval kujul, kahjuks näiteks MySQL DATETIME formaat YYYY-MM-DD HH:MM:SS selle jaoks ei sobi, tagastades vigase ajaväärtuse. Võimalik oleks aga kasutada kuju MM/DD/YYYY HH:MM:SS mis tuntakse ilusti ära. Üldiselt on toetatavad tekstiformaadid sõltuvad platvormist, seega tegelikult ei saa ühegi formaadi puhul teisenduse õigsuses lõpuni kindel olla.

Üksikute aja ja kuupäeva elementide esitamisel parameetritena numbrilisel kujul, on aasta ja kuu väärtused kohustuslikud ning ülejäänud 5 parameetrit valikulised. Juhul kui sisendiks anda ainult ainult aasta, peab funktsioon seda hoopis ajatempliks ja tagastab mitteoodatud tulemuse.

Juhul kui Date() on käivitatud ilma operaatorita new, jätab funktsioon parameetrid arvesse võtmata ning tagastab hetke aja stringi kujul.

Meeles tuleks ka pidada, et parameetrina antud aeg (kui selles pole üheselt märgitud ajatsooni näiteks GMT+0100 (Saksamaa)), tähistab alati lokaalset aega.

Date objekt sisaldab terve hulga erinevaid kasulikke meetodeid, mis abistavad ajaväärtustega tegelemisel.

Number date.getDate()

Meetod getDate tagastab Date objektis määratud lokaalse aja kuupäeva väärtuse vahemikus 1..31.

var aeg = new Date(2000,1,1);
aeg.getDate(); // 1

Number date.getDay()

Meetod getDay tagastab Date objektis määratud lokaalse aja nädalapäeva väärtuse vahemikus 0..6. Väärtus 0 tähistab pühapäeva ning väärtused 1..6 esmaspäeva-laupäeva.

Number date.getFullYear()

Meetod getFullYear tagastab Date objektis määratud lokaalse aja aasta väärtuse neljakohalise numbrina.

new Date().getFullYear(); // 2009

Number date.getHours()

Meetod getHours tagastab Date objektis määratud lokaalse aja tunni väärtuse vahemikus 0..23.

Number date.getMilliseconds()

Meetod getMilliseconds tagastab Date objektis määratud lokaalse aja millisekundite väärtuse viimasest sekundist vahemikus 0..999.

Number date.getMinutes()

Meetod getMinutes tagastab Date objektis määratud lokaalse aja minutite väärtuse viimasest tunnist vahemikus 0..59.

Number date.getMonth()

Meetod getMonth tagastab Date objektis määratud lokaalse aja kuu väärtuse vahemikus 0..11, kus 0 on jaanuar ning 11 detsember.

Number date.getSeconds()

Meetod getSeconds tagastab Date objektis määratud lokaalse aja sekundite väärtuse viimasest minutist vahemikus 0..59.

Number date.getTime()

Meetod getTime tagastab Date objektis määratud lokaalse aja väärtuse täisnumbri kujul millisekunditena alates 1. jaanuarist 1970.

Sellisel numbrilise kujul aja esitamine on kasulik kahe erineva aja vahel seose leidmiseks - kas siis teades kindlat vahemikku (näiteks 30 päeva) teada saada teist kuupäeva seoses olemasolevaga või näiteks kahe kuupäeva vahelise aja leidmiseks.

var d = new Date(new Date().getTime() + (100*3600*24*30));
alert('30 päeva pärast on aeg '+d);
 
var p = (new Date(2100,1,1).getTime() - new Date().getTime())/(100*3600*24)
alert('Aastani 2100 on veel jäänud '+p+' päeva');

Number date.getTimezoneOffset()

Meetod getTimezoneOffset tagastab Date objektis määratud lokaalse aja erinevuse GMT ajavööndi ajast minutites. Eestis on selleks väärtuseks talvel -120 ning suvel -180. Antud suurus on esitatud tundide asemel minutites, kuna osades riikides ei ole ajavööndid täistunnillise väärtusega, näiteks Indias on ajavöönd -05:30.

Kasulik on seda väärtust teada juhul kui soovitakse suvalises maailma punktis asuvale kasutajale näidata aega sõltuvalt tema asukohast. Server annab veebilehele aja mingi kindla ajavööndi, näiteks GMT järgi ning veebilehel olev JavaScript kirjutab selle aja vastavalt kasutaja enda vööndile dünaamiliselt üle.

Number date.getUTCDate()

Meetod getUTCDate tagastab Date objektis määratud aja universaalse vormi (GMT vööndi järgi) kuupäeva väärtuse vahemikus 1..31.

Number date.getUTCDay()

Meetod getUTCDay tagastab Date objektis määratud aja universaalse vormi (GMT vööndi järgi) nädalapäeva väärtuse vahemikus 0..6. Väärtus 0 tähistab pühapäeva ning väärtused 1..6 esmaspäeva-laupäeva.

Number date.getUTCFullYear()

Meetod getUTCFullYear tagastab Date objektis määratud aja universaalse vormi (GMT vööndi järgi) aasta väärtuse neljakohalise numbrina.

Number date.getUTCHours()

Meetod getUTCHours tagastab Date objektis määratud aja universaalse vormi (GMT vööndi järgi) tunni väärtuse vahemikus 0..23.

Number date.getUTCMilliseconds()

Meetod getUTCMilliseconds tagastab Date objektis määratud aja universaalse vormi (GMT vööndi järgi) millisekundite väärtuse viimasest sekundist vahemikus 0..999.

Number date.getUTCMinutes()

Meetod getUTCMinutes tagastab Date objektis määratud aja universaalse vormi (GMT vööndi järgi) minutite väärtuse viimasest tunnist vahemikus 0..59.

Number date.getUTCMonth()

Meetod getUTCMonth tagastab Date objektis määratud aja universaalse vormi (GMT vööndi järgi) kuu väärtuse vahemikus 0..11, kus 0 on jaanuar ning 11 detsember.

Number date.getUTCSeconds()

Meetod getUTCSeconds tagastab Date objektis määratud aja universaalse vormi (GMT vööndi järgi) sekundite väärtuse viimasest minutist vahemikus 0..59.

Number date.getYear()

Meetod getYear tagastab Date objektis oleva aja aasta väärtuse, millest lahutatakse suurus 1900. Algselt oli see mõeldud kahekohalise aastanumbri leidmiseks (nt. 1996 - 1900 = 96), kuid alates aastast 2000 on funktsioon muutunud sisuliselt kasutuks, tagastades aasta väärtuseks segasevõitu kolmekohalise numbri.

new Date().getYear(); // 109

Meetodi getYear asemel tuleks õige tulemuse saamiseks kasutada meetodit getFullYear.

Number Date.parse(String ajastring)

Meetod Date.parse on globaalse objekti Date staatiliselt meetodiks. See tähendab, et meetod ei liigu Date tüüpi objektide loomisel uute objektide juurde kaasa. Meetod võtab sisendiks stringi kujul ajaväärtuse ja teisendab selle millisekundite kujul ajatempliks.

var t = Date.parse("12/24/2009 13:30:00");
alert(t); // 1261650600000

Meetod on kasulik juhul, kui on tarvis teisendada ajastring ajatempliks, kuid ei soovita luua selle jaoks uut Date tüüpi objekti.

Number date.setDate(Number päev)

Meetod setDate võtab parameetriks kuupäeva (kohaliku aja järgi) vahemikus 1..31 ning seab selle Date objektiga seotud aja kuupäevaks. Meetodi tagastusväärtuseks on saadud aeg millisekundites.

var d = new Date(2000,3,13);
d.setDate(14); // 955659600000

Number date.setFullYear(Number aasta [, Number kuu [, Number päev]])

Meetod setFullYear võtab parameetriks neljakohalise numbriga aasta (kohaliku aja järgi) ning seab selle Date objektiga seotud aja aastaks. Meetodi tagastusväärtuseks on saadud aeg millisekundites.

Valikuliselt on sama meetodiga võimalik seada ka kuud ning kuupäeva. Selleks tuleks kasutada kahte lisaparameetrit kuu (vahemikus 0..11) ning päev (vahemikus 1..31).

Number date.setHours(Number tund [, Number minut [, Number sekund [, Number ms]]])

Meetod setHours võtab parameetriks tunni (kohaliku aja järgi) vahemikus 0..23 ning seab selle Date objektiga seotud aja tunniks. Meetodi tagastusväärtuseks on saadud aeg millisekundites.

Meetodil on veel kolm valikulist lisaparameetrit, millega saab seada ka minutit, sekundit ja millisekundit.

Number date.setMilliseconds(Number ms)

Meetod võimaldab seada Date objekti millisekundiosa väärtust (kohaliku aja järgi). Parameeter ms peab olema vahemikus 0..999. Meetodi tagastusväärtuseks on saadud aeg millisekundites.

Number date.setMinutes(Number minutid [, Number sekund [, Number ms]])

Meetod setMinutes võtab parameetriks minuti väärtuse (kohaliku aja järgi) vahemikus 0..59 ning seab selle Date objektiga seotud aja minuti väärtuseks. Meetodi tagastusväärtuseks on saadud aeg millisekundites.

Meetodil on veel kaks valikulist lisaparameetrit, millega saab seada ka sekundit ja millisekundit.

Number date.setMonth(Number kuu [, Number päev])

Meetod setMonth võtab parameetriks kuu väärtuse (kohaliku aja järgi) vahemikus 0..11 ning seab selle Date objektiga seotud aja kuu väärtuseks. Meetodi tagastusväärtuseks on saadud aeg millisekundites.

Valikuliselt on sama meetodiga võimalik seada ka kuupäeva. Selleks tuleks kasutada kuupäeva lisaparameetrit, kus kuupäev on vahemikus 1..31.

Number date.setSeconds(Number sekund [, Number ms])

Meetod setSeconds võtab parameetriks sekundi väärtuse (kohaliku aja järgi) vahemikus 0..59 ning seab selle Date objektiga seotud aja sekundi väärtuseks. Meetodi tagastusväärtuseks on saadud aeg millisekundites.

Meetodil on veel valikuline lisaparameeter, millega saab seada ka millisekundit.

Number date.setTime(Number ajatempel)

Meetodiga saab seada Date objekti ajaväärtust andes sellele parameetriks ajatempli millisekundite kujul. Ajatempli genereerimiseks on mugav kasutada funktsiooni Date.parse.

var d = new Date();
d.setTime(Date.parse('2005/12/31 15:50:00')); // 1136033400000

Meetodi tagastusväärtuseks on sisendiks saadud millisekundite väärtus.

Number date.setUTCDate(Number päev)

Meetod setUTCDate võtab parameetriks kuupäeva (universaalse GMT aja järgi) vahemikus 1..31 ning seab selle Date objektiga seotud aja kuupäevaks. Meetodi tagastusväärtuseks on saadud aeg millisekundites.

var d = new Date(2000,3,13);
d.setUTCDate(14); // 955746000000

Number date.setUTCFullYear(Number aasta [, Number kuu [, Number päev]])

Meetod setUTCFullYear võtab parameetriks neljakohalise numbriga aasta (universaalse GMT järgi) ning seab selle Date objektiga seotud aja aastaks. Meetodi tagastusväärtuseks on saadud aeg millisekundites.

Valikuliselt on sama meetodiga võimalik seada ka kuud ning kuupäeva. Selleks tuleks kasutada kahte lisaparameetrit kuu (vahemikus 0..11) ning päev (vahemikus 1..31).

Number date.setUTCHours(Number tund [, Number minut [, Number sekund [, Number ms]]])

Meetod setUTCHours võtab parameetriks tunni (universaalse GMT järgi) vahemikus 0..23 ning seab selle Date objektiga seotud aja tunniks. Meetodi tagastusväärtuseks on saadud aeg millisekundites.

Meetodil on veel kolm valikulist lisaparameetrit, millega saab seada ka minutit, sekundit ja millisekundit.

Number date.setUTCMilliseconds(Number ms)

Meetod võimaldab seada Date objekti millisekundiosa väärtust (universaalse GMT järgi). Parameeter ms peab olema vahemikus 0..999. Meetodi tagastusväärtuseks on saadud aeg millisekundites.

Number date.setUTCMinutes(Number minutid [, Number sekund [, Number ms]])

Meetod setUTCMinutes võtab parameetriks minuti väärtuse (universaalse GMT järgi) vahemikus 0..59 ning seab selle Date objektiga seotud aja minuti väärtuseks. Meetodi tagastusväärtuseks on saadud aeg millisekundites.

Meetodil on veel kaks valikulist lisaparameetrit, millega saab seada ka sekundit ja millisekundit.

Number date.setUTCMonth(Number kuu [, Number päev])

Meetod setUTCMonth võtab parameetriks kuu väärtuse (universaalse GMT järgi) vahemikus 0..11 ning seab selle Date objektiga seotud aja kuu väärtuseks. Meetodi tagastusväärtuseks on saadud aeg millisekundites.

Valikuliselt on sama meetodiga võimalik seada ka kuupäeva. Selleks tuleks kasutada lisaparameetrit päev (vahemikus 1..31).

Number date.setUTCSeconds(Number sekund [, Number ms])

Meetod setUTCSeconds võtab parameetriks sekundi väärtuse (universaalse GMT järgi) vahemikus 0..59 ning seab selle Date objektiga seotud aja sekundi väärtuseks. Meetodi tagastusväärtuseks on saadud aeg millisekundites.

Meetodil on veel valikuline lisaparameeter, millega saab seada ka millisekundit.

Number date.setYear(Number aasta)

Meetod setYear võtab sisendiks aasta väärtuse (kohaliku aja järgi). Juhul kui aasta väärtus jääb vahemikku 0..99, liidetakse sellele väärtus 1900. Tegu on praeguseks ajaks suhteliselt kasutu featuuriga ning seega tuleb jääda neljakohaliste numbrite juurde.

String date.toDateString()

Meetod väljastab kuupäeva väärtuse kohaliku aja järgi stringina inimloetaval kujul. Täpne vorm sõltub kasutatavast platvormist.

new Date().toDateString(); // Fri Jun 05 2009

String date.toGMTString()

Meetod väljastab kuupäeva ja aja väärtuse universaalse GMT aja järgi stringina inimloetaval kujul. Täpne vorm sõltub kasutatavast platvormist.

new Date().toGMTString(); // Thu, 04 Jun 2009 22:10:17 GMT

String date.toLocaleDateString()

Meetod väljastab kuupäeva väärtuse kohaliku aja järgi stringina inimloetaval kujul, arvestades kasutaja lokaali. Täpne vorm sõltub kasutatavast platvormist.

new Date().toLocaleDateString(); // 06/05/2009

String date.toLocaleString()

Meetod väljastab kuupäeva ja aja väärtuse kohaliku aja järgi stringina inimloetaval kujul, arvestades kasutaja lokaali. Täpne vorm sõltub kasutatavast platvormist.

new Date().toLocaleString(); // Fri Jun 5 01:14:31 2009

String date.toLocaleTimeString()

Meetod väljastab aja väärtuse kohaliku aja järgi stringina inimloetaval kujul, arvestades kasutaja lokaali. Täpne vorm sõltub kasutatavast platvormist.

new Date().toLocaleTimeString(); // 01:15:54

String date.toString()

Meetod toString tagastab kuupäeva ja aja väärtuse kohaliku järgi stringina inimloetaval kujul. Täpne vorm sõltub kasutatavast platvormist.

new Date().toString(); // Fri Jun 05 2009 01:19:57 GMT+0300 (EEST)

String date.toTimeString()

Meetod väljastab aja väärtuse kohaliku aja järgi stringina inimloetaval kujul. Täpne vorm sõltub kasutatavast platvormist.

new Date().toTimeString(); // 01:17:08 GMT+0300 (EEST)

String date.toUTCString()

Meetod väljastab kuupäeva ja aja väärtuse universaalse GMT vööndiaja järgi stringina inimloetaval kujul. Täpne vorm sõltub kasutatavast platvormist.

new Date().toLocaleString(); // Thu, 04 Jun 2009 22:17:33 GMT

Number Date.UTC([Number aasta [, Number kuu [, Number päev [, Number tund [, Number minut [, Number sekund [, Number ms]]]]]]])

Meetod UTC on sarnaselt Date.parse meetodiga globaalse objekti Date staatiliseks meetodiks. Meetod võtab sisendiks GMT ajavööndi aja 7 parameetri kujul ning tagastab ajatempli millisekunditena. Kasutatavad 7 parameetrit on kõik valikulised.

Meetodit on mugav kasutada Date objekti loomiseks, kui teada on universaalne GTM aeg, kuid konstruktor Date eeldab lokaalset aega.

var d = new Date(Date.UTC(aasta, kuu, päev, tund, minut, sekund, ms));

Sellisel juhul loob Date.UTC GMT aja järgi ajatempli (mis on alati universaalne) ning edastab selle konstruktorfunktsiooni Date parameetriks.

Number date.valueOf()

Sama mis getTime. Meetod tagastab Date objekti ajaväärtuse ajatemplina millisekundite väärtusena. Meetod on vajalik teisendusteks, kus Date objekti üritatakse kasutada numbrilises kontekstis.