strnlen, strnlen_s, wcsnlen, wcsnlen_s, _mbsnlen, _mbsnlen_l, _mbstrnlen, _mbstrnlen_l

Mendapatkan panjang string dengan menggunakan lokal saat ini atau yang telah diteruskan. Fungsi-fungsi ini adalah versi yang lebih aman dari , , wcslen, _mbslen_mbslen_l, _mbstrlen, _mbstrlen_l.strlen

Penting

_mbsnlen, , _mbsnlen_l_mbstrnlen, dan _mbstrnlen_l tidak dapat digunakan dalam aplikasi yang dijalankan di Windows Runtime. Untuk informasi selengkapnya, lihat Fungsi CRT yang tidak didukung di aplikasi Platform Windows Universal.

Sintaks

size_t strnlen(
   const char *str,
   size_t numberOfElements
);
size_t strnlen_s(
   const char *str,
   size_t numberOfElements
);
size_t wcsnlen(
   const wchar_t *str,
   size_t numberOfElements
);
size_t wcsnlen_s(
   const wchar_t *str,
   size_t numberOfElements
);
size_t _mbsnlen(
   const unsigned char *str,
   size_t numberOfElements
);
size_t _mbsnlen_l(
   const unsigned char *str,
   size_t numberOfElements,
   _locale_t locale
);
size_t _mbstrnlen(
   const char *str,
   size_t numberOfElements
);
size_t _mbstrnlen_l(
   const char *str,
   size_t numberOfElements,
   _locale_t locale
);

Parameter

str
Untai (karakter) null-terminated.

numberOfElements
Ukuran buffer string.

locale
Lokal untuk digunakan.

Nilai hasil

Fungsi-fungsi ini mengembalikan jumlah karakter dalam string, tidak termasuk karakter null yang dihentikan. Jika tidak ada terminator null dalam byte pertama numberOfElements string (atau karakter lebar untuk wcsnlen), maka numberOfElements dikembalikan untuk menunjukkan kondisi kesalahan; string null-terminated memiliki panjang yang benar-benar kurang dari numberOfElements.

_mbstrnlen dan _mbstrnlen_l kembalikan -1 jika string berisi karakter multibyte yang tidak valid.

Keterangan

Catatan

strnlen bukan pengganti untuk strlen; strnlen dimaksudkan untuk digunakan hanya untuk menghitung ukuran data yang tidak tepercaya masuk dalam buffer ukuran yang diketahui—misalnya, paket jaringan. strnlen menghitung panjang tetapi tidak berjalan melewati akhir buffer jika string tidak ditentukan. Untuk situasi lain, gunakan strlen. (Hal yang sama berlaku untuk wcsnlen, , _mbsnlendan _mbstrnlen.)

Masing-masing fungsi ini mengembalikan jumlah karakter dalam str, tidak termasuk karakter null yang dihentikan. Namun, strnlen dan strnlen_s menginterpretasikan string sebagai string karakter byte tunggal dan oleh karena itu, nilai pengembalian selalu sama dengan jumlah byte, bahkan jika string berisi karakter multibyte. wcsnlen dan wcsnlen_s masing-masing adalah versi strnlen karakter lebar dari dan strnlen_s masing-masing; argumen untuk wcsnlen dan wcsnlen_s adalah string karakter lebar dan jumlah karakter berada dalam unit karakter lebar. Jika tidak, wcsnlen dan strnlen berulah identik, seperti halnya strnlen_s dan wcsnlen_s.

strnlen, wcsnlen, dan _mbsnlen jangan validasi parameternya. Jika str adalah NULL, pelanggaran akses terjadi.

strnlen_s dan wcsnlen_s memvalidasi parameternya. Jika str adalah NULL, fungsi mengembalikan 0.

_mbstrnlen juga memvalidasi parameternya. Jika str adalah NULL, atau jika numberOfElements lebih besar dari INT_MAX, _mbstrnlen menghasilkan pengecualian parameter yang tidak valid, seperti yang dijelaskan dalam Validasi parameter. Jika eksekusi diizinkan untuk melanjutkan, _mbstrnlen atur errno ke EINVAL dan kembalikan -1.

Secara default, status global fungsi ini dicakup ke aplikasi. Untuk mengubah perilaku ini, lihat Status global di CRT.

Pemetaan rutin teks generik

TCHAR.H Rutin	_UNICODE dan _MBCS tidak ditentukan	_MBCS Didefinisikan	_UNICODE Didefinisikan
_tcsnlen	strnlen	strnlen	wcsnlen
_tcscnlen	strnlen	_mbsnlen	wcsnlen
_tcscnlen_l	strnlen	_mbsnlen_l	wcsnlen

_mbsnlen dan _mbstrnlen mengembalikan jumlah karakter multibyte dalam string multibyte-character. _mbsnlen mengenali urutan karakter multibyte sesuai dengan halaman kode multibyte yang saat ini digunakan atau sesuai dengan lokal yang diteruskan; ini tidak menguji validitas multibyte-character. _mbstrnlen pengujian untuk validitas karakter multibyte dan mengenali urutan karakter multibyte. Jika string yang diteruskan ke _mbstrnlen berisi karakter multibyte yang tidak valid, errno diatur ke EILSEQ.

Nilai output dipengaruhi oleh pengaturan LC_CTYPE pengaturan kategori lokal. Untuk informasi selengkapnya, lihat setlocale . Versi fungsi ini identik, kecuali yang tidak memiliki _l akhiran menggunakan lokal saat ini untuk perilaku dependen lokal ini dan versi yang memiliki _l akhiran, sebagai gantinya, gunakan parameter lokal yang diteruskan. Untuk informasi selengkapnya, lihat Lokal.

Persyaratan

Rutin	Header yang diperlukan
strnlen, strnlen_s	<string.h>
wcsnlen, wcsnlen_s	<string.h> atau <wchar.h>
_mbsnlen, _mbsnlen_l	<mbstring.h>
_mbstrnlen, _mbstrnlen_l	<stdlib.h>

Untuk informasi kompatibilitas selengkapnya, lihat Kompatibilitas.

Contoh

// crt_strnlen.c

#include <string.h>

int main()
{
   // str1 is 82 characters long. str2 is 159 characters long

   char* str1 = "The length of a string is the number of characters\n"
               "excluding the terminating null.";
   char* str2 = "strnlen takes a maximum size. If the string is longer\n"
                "than the maximum size specified, the maximum size is\n"
                "returned rather than the actual size of the string.";
   size_t len;
   size_t maxsize = 100;

   len = strnlen(str1, maxsize);
   printf("%s\n Length: %d \n\n", str1, len);

   len = strnlen(str2, maxsize);
   printf("%s\n Length: %d \n", str2, len);
}

The length of a string is the number of characters
excluding the terminating null.
Length: 82

strnlen takes a maximum size. If the string is longer
than the maximum size specified, the maximum size is
returned rather than the actual size of the string.
Length: 100

Baca juga

Manipulasi string
Lokal
Interpretasi urutan karakter multibyte
setlocale, _wsetlocale
strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l
strncmp, wcsncmp, _mbsncmp, _mbsncmp_l
strcoll Fungsi
strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l
strrchr, wcsrchr, _mbsrchr, _mbsrchr_l
_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l
strspn, wcsspn, _mbsspn, _mbsspn_l