Fungsi GetDateFormatEx (datetimeapi.h)
Memformat tanggal sebagai string tanggal untuk lokal yang ditentukan oleh nama. Fungsi memformat tanggal yang ditentukan atau tanggal sistem lokal.
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.
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
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 |