Fungsi GetDateFormatEx (datetimeapi.h)

Artikel
08/23/2023

Memformat tanggal sebagai string tanggal untuk lokal yang ditentukan oleh nama. Fungsi memformat tanggal yang ditentukan atau tanggal sistem lokal.

Catatan Aplikasi harus memanggil fungsi ini disukai ke GetDateFormat jika dirancang untuk berjalan hanya di Windows Vista dan yang lebih baru.

Catatan Fungsi ini dapat memformat data yang berubah antar rilis, misalnya, karena lokal kustom. Jika aplikasi Anda harus mempertahankan atau mengirimkan data, lihat Menggunakan Data Lokal Persisten.

Sintaks

int GetDateFormatEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpDate,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpDateStr,
  [in]            int              cchDate,
  [in, optional]  LPCWSTR          lpCalendar
);

Parameter

[in, optional] lpLocaleName

Arahkan ke nama lokal, atau salah satu nilai yang telah ditentukan sebelumnya berikut ini.

[in] dwFlags

Bendera yang menentukan berbagai opsi fungsi yang dapat diatur jika lpFormat diatur ke NULL. Aplikasi dapat menentukan kombinasi nilai dan LOCALE_USE_CP_ACP atau LOCALE_NOUSEROVERRIDE berikut.

Hati Penggunaan LOCALE_NOUSEROVERRIDE sangat tidak disarankan karena menonaktifkan preferensi pengguna.

Nilai	Makna
DATE_AUTOLAYOUT	Windows 7 dan yang lebih baru: Deteksi kebutuhan akan tata letak bacaan kanan-ke-kiri dan kiri-ke-kanan menggunakan informasi lokal dan kalender, dan tambahkan tanda yang sesuai. Nilai ini tidak dapat digunakan dengan DATE_LTRREADING atau DATE_RTLREADING. DATE_AUTOLAYOUT lebih disukai daripada DATE_LTRREADING dan DATE_RTLREADING karena menggunakan lokal dan kalender untuk menentukan penambahan tanda yang benar.
DATE_LONGDATE	Gunakan format tanggal panjang. Nilai ini tidak dapat digunakan dengan DATE_MONTHDAY, DATE_SHORTDATE, atau DATE_YEARMONTH.
DATE_LTRREADING	Tambahkan tanda untuk tata letak baca kiri-ke-kanan. Nilai ini tidak dapat digunakan dengan DATE_RTLREADING.
DATE_RTLREADING	Tambahkan tanda untuk tata letak baca kanan-ke-kiri. Nilai ini tidak dapat digunakan dengan DATE_LTRREADING
DATE_SHORTDATE	Gunakan format tanggal pendek. Ini adalah default. Nilai ini tidak dapat digunakan dengan DATE_MONTHDAY, DATE_LONGDATE, atau DATE_YEARMONTH.
DATE_USE_ALT_CALENDAR	Gunakan kalender alternatif, jika ada, untuk memformat string tanggal. Jika bendera ini diatur, fungsi menggunakan format default untuk kalender alternatif tersebut, daripada menggunakan penimpaan pengguna apa pun. Penimpaan pengguna hanya akan digunakan jika tidak ada format default untuk kalender alternatif yang ditentukan.
DATE_YEARMONTH	Windows Vista: Gunakan format tahun/bulan. Nilai ini tidak dapat digunakan dengan DATE_MONTHDAY, DATE_SHORTDATE, atau DATE_LONGDATE.
DATE_MONTHDAY	Windows 10: Gunakan kombinasi format bulan dan hari yang sesuai untuk lokal yang ditentukan. Nilai ini tidak dapat digunakan dengan DATE_YEARMONTH, DATE_SHORTDATE, atau DATE_LONGDATE.

Jika aplikasi tidak menentukan DATE_YEARMONTH, DATE_MONTHDAY, DATE_SHORTDATE, atau DATE_LONGDATE, dan lpFormat diatur ke NULL, DATE_SHORTDATE adalah default.

[in, optional] lpDate

Penunjuk ke struktur SYSTEMTIME yang berisi informasi tanggal untuk diformat. Aplikasi dapat mengatur parameter ini ke NULL jika fungsinya adalah menggunakan tanggal sistem lokal saat ini.

[in, optional] lpFormat

Penunjuk ke format string gambar yang digunakan untuk membentuk tanggal. Nilai yang mungkin untuk format string gambar ditentukan dalam Hari, Bulan, Tahun, dan Format Era Gambar.

Misalnya, untuk mendapatkan string tanggal "Wed, Agustus 31 94", aplikasi menggunakan string gambar "ddd',' MMM dd yy".

Fungsi ini menggunakan lokal yang ditentukan hanya untuk informasi yang tidak ditentukan dalam format string gambar, misalnya, nama hari dan bulan untuk lokal. Aplikasi dapat mengatur parameter ini ke NULL untuk memformat string sesuai dengan format tanggal untuk lokal yang ditentukan.

[out, optional] lpDateStr

Penunjuk ke buffer tempat fungsi ini mengambil string tanggal yang diformat.

[in] cchDate

Ukuran, dalam karakter, dari buffer lpDateStr . Aplikasi dapat mengatur parameter ini ke 0 untuk mengembalikan ukuran buffer yang diperlukan untuk menahan string tanggal yang diformat. Dalam hal ini, buffer yang ditunjukkan oleh lpDateStr tidak digunakan.

[in, optional] lpCalendar

Dipesan; harus diatur ke NULL.

Mengembalikan nilai

Mengembalikan jumlah karakter yang ditulis ke buffer lpDateStr jika berhasil. Jika parameter cchDate diatur ke 0, fungsi mengembalikan jumlah karakter yang diperlukan untuk menahan string tanggal yang diformat, termasuk karakter null yang mengakhiri.

Fungsi ini mengembalikan 0 jika tidak berhasil. Untuk mendapatkan informasi kesalahan yang diperluas, aplikasi dapat memanggil GetLastError, yang dapat mengembalikan salah satu kode kesalahan berikut:

ERROR_INSUFFICIENT_BUFFER. Ukuran buffer yang disediakan tidak cukup besar, atau salah diatur ke NULL.
ERROR_INVALID_FLAGS. Nilai yang diberikan untuk bendera tidak valid.
ERROR_INVALID_PARAMETER. Salah satu nilai parameter tidak valid.

Keterangan

Catatan API ini sedang diperbarui untuk mendukung perubahan era Jepang Mei 2019. Jika aplikasi Anda mendukung kalender Jepang, Anda harus memvalidasi bahwa aplikasi tersebut menangani era baru dengan benar. Lihat Menyiapkan aplikasi Anda untuk perubahan era Jepang untuk informasi selengkapnya.

Tanggal paling awal yang didukung oleh fungsi ini adalah 1 Januari 1601.

Nama hari, nama hari yang disingkat, nama bulan, dan nama bulan yang disingkat semuanya dilokalkan berdasarkan pengidentifikasi lokal.

Nilai tanggal dalam struktur yang ditunjukkan oleh lpDate harus valid. Fungsi ini memeriksa setiap nilai tanggal: tahun, bulan, hari, dan hari dalam seminggu. Jika hari dalam seminggu salah, fungsi menggunakan nilai yang benar, dan tidak mengembalikan kesalahan. Jika salah satu nilai tanggal lainnya berada di luar rentang yang benar, fungsi gagal, dan mengatur kesalahan terakhir ke ERROR_INVALID_PARAMETER.

Fungsi mengabaikan anggota waktu struktur SYSTEMTIME yang ditunjukkan oleh lpDate. Ini termasuk wHour, wMinute, wSecond, dan wMilliseconds.

Jika parameter lpFormat berisi string format yang buruk, fungsi tidak mengembalikan kesalahan, tetapi hanya membentuk string tanggal terbaik. Misalnya, satu-satunya gambar tahun yang valid adalah L"yyyy" dan L"yy", di mana "L" menunjukkan string Unicode (karakter 16-bit). Jika L"y" diteruskan, fungsi mengasumsikan L"yy". Jika L"yyy" diteruskan, fungsi mengasumsikan L"yyyy". Jika lebih dari empat gambar tanggal (L"dddd") atau empat bulan (L"MMMM") diteruskan, fungsi default ke L"dddd" atau L"MMMM".

Aplikasi harus mengapit teks apa pun yang harus tetap dalam bentuk yang tepat dalam string tanggal dalam tanda kutip tunggal dalam gambar format tanggal. Tanda kutip tunggal juga dapat digunakan sebagai karakter escape untuk memungkinkan tanda kutip tunggal itu sendiri ditampilkan dalam string tanggal. Namun, urutan escape harus diapit dalam dua tanda kutip tunggal. Misalnya, untuk menampilkan tanggal sebagai "Mei '93", string formatnya adalah: L"MMMM '''yy". Tanda kutip tunggal pertama dan terakhir adalah tanda kutip penutup. Tanda kutip tunggal kedua dan ketiga adalah urutan escape untuk memungkinkan tanda kutip tunggal ditampilkan sebelum abad tersebut.

Ketika gambar tanggal berisi bentuk numerik hari itu (baik d atau dd) dan nama bulan penuh (MMMM), bentuk genitif nama bulan diambil dalam string tanggal.

Untuk mendapatkan format tanggal pendek dan panjang default tanpa melakukan pemformatan aktual, aplikasi harus menggunakan GetLocaleInfoEx dengan konstanta LOCALE_SSHORTDATE atau LOCALE_SLONGDATE . Untuk mendapatkan format tanggal untuk kalender alternatif, aplikasi menggunakan GetLocaleInfoEx dengan konstanta LOCALE_IOPTIONALCALENDAR . Untuk mendapatkan format tanggal untuk kalender tertentu, aplikasi menggunakan GetCalendarInfoEx, meneruskan Pengidentifikasi Kalender yang sesuai. Ini dapat memanggil EnumCalendarInfoEx atau EnumDateFormatsEx untuk mengambil format tanggal untuk kalender tertentu.

Fungsi ini dapat mengambil data dari lokal kustom. Data tidak dijamin sama dari komputer ke komputer atau antara eksekusi aplikasi. Jika aplikasi Anda harus mempertahankan atau mengirimkan data, lihat Menggunakan Data Lokal Persisten.

Format DATE_LONGDATE mencakup dua jenis pola tanggal: pola yang mencakup hari dalam seminggu dan pola yang tidak menyertakan hari dalam seminggu. Misalnya, "Selasa, 18 Oktober 2016" atau "18 Oktober 2016". Jika aplikasi Anda perlu memastikan bahwa tanggal menggunakan salah satu pola semacam ini dan bukan jenis lainnya, aplikasi Anda harus melakukan tindakan berikut:

Panggil fungsi EnumDateFormatsExEx untuk mendapatkan semua format tanggal untuk format DATE_LONGDATE.
Cari format tanggal pertama yang diteruskan ke fungsi panggilan balik yang Anda tentukan untuk EnumDateFormatsExEx yang cocok dengan pengidentifikasi kalender yang Anda minta dan memiliki string format tanggal yang cocok dengan persyaratan aplikasi Anda. Misalnya, cari format tanggal pertama yang menyertakan "dddd" jika aplikasi Anda mengharuskan tanggal tersebut menyertakan nama lengkap hari dalam seminggu, atau cari format tanggal pertama yang tidak menyertakan "ddd" atau "dddd" jika aplikasi Anda mengharuskan tanggal tersebut menyertakan nama singkatan atau nama lengkap hari dalam seminggu.
Panggil fungsi GetDateFormatEx dengan parameter lpFormat yang diatur ke string format tanggal yang Anda identifikasi sebagai format yang sesuai dalam fungsi panggilan balik.

Jika kehadiran atau tidak adanya hari dalam seminggu dalam format tanggal panjang tidak masalah bagi aplikasi Anda, aplikasi Anda dapat memanggil GetDateFormatEx secara langsung tanpa terlebih dahulu menghitung semua format tanggal panjang dengan memanggil EnumDateFormatsExEx.

Dimulai di Windows 8: Jika aplikasi Anda meneruskan tag bahasa ke fungsi ini dari namespace Windows.Globalization, aplikasi harus terlebih dahulu mengonversi tag dengan memanggil ResolveLocaleName.

Dimulai di Windows 8: GetDateFormatEx dideklarasikan dalam Datetimeapi.h. Sebelum Windows 8, itu dinyatakan di Winnls.h.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2008 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	datetimeapi.h
Pustaka	Kernel32.lib
DLL	Kernel32.dll