string.h

Go to the documentation of this file.

//
// string.h
//
//      Copyright (c) Microsoft Corporation. All rights reserved.
//
// The C Standard Library <string.h> header.
//
#pragma once
#define _INC_STRING

#include <corecrt.h>
#include <corecrt_memory.h>
#include <corecrt_wstring.h>
#include <vcruntime_string.h>

#ifndef __midl

_CRT_BEGIN_C_HEADER



#define _NLSCMPERROR _CRT_INT_MAX // currently == INT_MAX

#if __STDC_WANT_SECURE_LIB__

    _Check_return_wat_
    _ACRTIMP errno_t __cdecl strcpy_s(
        _Out_writes_z_(_SizeInBytes) char*       _Destination,
        _In_                         rsize_t     _SizeInBytes,
        _In_z_                       char const* _Source
        );

    _Check_return_wat_
    _ACRTIMP errno_t __cdecl strcat_s(
        _Inout_updates_z_(_SizeInBytes) char*       _Destination,
        _In_                            rsize_t     _SizeInBytes,
        _In_z_                          char const* _Source
        );

    _Check_return_wat_
    _ACRTIMP errno_t __cdecl strerror_s(
        _Out_writes_z_(_SizeInBytes) char*  _Buffer,
        _In_                         size_t _SizeInBytes,
        _In_                         int    _ErrorNumber);

    _Check_return_wat_
    _ACRTIMP errno_t __cdecl strncat_s(
        _Inout_updates_z_(_SizeInBytes) char*       _Destination,
        _In_                            rsize_t     _SizeInBytes,
        _In_reads_or_z_(_MaxCount)      char const* _Source,
        _In_                            rsize_t     _MaxCount
        );

    _Check_return_wat_
    _ACRTIMP errno_t __cdecl strncpy_s(
        _Out_writes_z_(_SizeInBytes) char*       _Destination,
        _In_                         rsize_t     _SizeInBytes,
        _In_reads_or_z_(_MaxCount)   char const* _Source,
        _In_                         rsize_t     _MaxCount
        );

    _Check_return_
    _ACRTIMP char*  __cdecl strtok_s(
        _Inout_opt_z_                 char*       _String,
        _In_z_                        char const* _Delimiter,
        _Inout_ _Deref_prepost_opt_z_ char**      _Context
        );

#endif // __STDC_WANT_SECURE_LIB__

_ACRTIMP void* __cdecl _memccpy(
    _Out_writes_bytes_opt_(_MaxCount) void*       _Dst,
    _In_                              void const* _Src,
    _In_                              int         _Val,
    _In_                              size_t      _MaxCount
    );

__DEFINE_CPP_OVERLOAD_SECURE_FUNC_0_1(
    errno_t, strcat_s,
           char,        _Destination,
    _In_z_ char const*, _Source
    )

#ifndef RC_INVOKED

#pragma warning(push)
#pragma warning(disable: 28719) // __WARNING_BANNED_API_USAGE
#pragma warning(disable: 28726) // __WARNING_BANNED_API_USAGEL2
    __DEFINE_CPP_OVERLOAD_STANDARD_FUNC_0_1(
        char*, __RETURN_POLICY_DST, __EMPTY_DECLSPEC, strcat,
        _Inout_updates_z_(_String_length_(_Destination) + _String_length_(_Source) + 1), char,        _Destination,
        _In_z_                                                                           char const*, _Source
        )
#pragma warning(pop)

#endif // RC_INVOKED

_Check_return_
int __cdecl strcmp(
    _In_z_ char const* _Str1,
    _In_z_ char const* _Str2
    );

_Check_return_
_ACRTIMP int __cdecl _strcmpi(
    _In_z_ char const* _String1,
    _In_z_ char const* _String2
    );

_Check_return_
_ACRTIMP int __cdecl strcoll(
    _In_z_ char const* _String1,
    _In_z_ char const* _String2
    );

_Check_return_
_ACRTIMP int __cdecl _strcoll_l(
    _In_z_   char const* _String1,
    _In_z_   char const* _String2,
    _In_opt_ _locale_t   _Locale
    );

__DEFINE_CPP_OVERLOAD_SECURE_FUNC_0_1(
    errno_t, strcpy_s,
    _Post_z_ char,        _Destination,
    _In_z_   char const*, _Source
    )

#pragma warning(push)
#pragma warning(disable: 28719) // __WARNING_BANNED_API_USAGE
#pragma warning(disable: 28726) // __WARNING_BANNED_API_USAGEL2
__DEFINE_CPP_OVERLOAD_STANDARD_FUNC_0_1(
    char*, __RETURN_POLICY_DST, __EMPTY_DECLSPEC, strcpy,
    _Out_writes_z_(_String_length_(_Source) + 1), char,        _Destination,
    _In_z_                                        char const*, _Source
    )
#pragma warning(pop)

_Check_return_
_ACRTIMP size_t __cdecl strcspn(
    _In_z_ char const* _Str,
    _In_z_ char const* _Control
    );

#if defined _DEBUG && defined _CRTDBG_MAP_ALLOC
    #pragma push_macro("_strdup")
    #undef _strdup
#endif

_Check_return_
_ACRTIMP _CRTALLOCATOR char* __cdecl _strdup(
    _In_opt_z_ char const* _Source
    );

#if defined _DEBUG && defined _CRTDBG_MAP_ALLOC
    #pragma pop_macro("_strdup")
#endif

_Ret_z_
_Success_(return != 0)
_Check_return_ _CRT_INSECURE_DEPRECATE(_strerror_s)
_ACRTIMP char*  __cdecl _strerror(
    _In_opt_z_ char const* _ErrorMessage
    );

_Check_return_wat_
_ACRTIMP errno_t __cdecl _strerror_s(
    _Out_writes_z_(_SizeInBytes) char*       _Buffer,
    _In_                         size_t      _SizeInBytes,
    _In_opt_z_                   char const* _ErrorMessage
    );

__DEFINE_CPP_OVERLOAD_SECURE_FUNC_0_1(
    errno_t, _strerror_s,
               char,        _Buffer,
    _In_opt_z_ char const*, _ErrorMessage
    )

_Ret_z_
_Check_return_ _CRT_INSECURE_DEPRECATE(strerror_s)
_ACRTIMP char* __cdecl strerror(
    _In_ int _ErrorMessage
    );

__DEFINE_CPP_OVERLOAD_SECURE_FUNC_0_1(
    errno_t, strerror_s,
        char, _Buffer,
    _In_ int, _ErrorMessage
    )

_Check_return_
_ACRTIMP int __cdecl _stricmp(
    _In_z_ char const* _String1,
    _In_z_ char const* _String2
    );

_Check_return_
_ACRTIMP int __cdecl _stricoll(
    _In_z_ char const* _String1,
    _In_z_ char const* _String2
    );

_Check_return_
_ACRTIMP int __cdecl _stricoll_l(
    _In_z_   char const* _String1,
    _In_z_   char const* _String2,
    _In_opt_ _locale_t   _Locale
    );

_Check_return_
_ACRTIMP int __cdecl _stricmp_l(
    _In_z_   char const* _String1,
    _In_z_   char const* _String2,
    _In_opt_ _locale_t   _Locale
    );

_Check_return_
size_t __cdecl strlen(
    _In_z_ char const* _Str
    );

_Check_return_wat_
_ACRTIMP errno_t __cdecl _strlwr_s(
    _Inout_updates_z_(_Size) char*  _String,
    _In_                     size_t _Size
    );

__DEFINE_CPP_OVERLOAD_SECURE_FUNC_0_0(
    errno_t, _strlwr_s,
    _Prepost_z_ char, _String
    )

__DEFINE_CPP_OVERLOAD_STANDARD_FUNC_0_0(
    char*, __RETURN_POLICY_DST, _ACRTIMP, _strlwr,
    _Inout_z_, char, _String
    )

_Check_return_wat_
_ACRTIMP errno_t __cdecl _strlwr_s_l(
    _Inout_updates_z_(_Size) char*     _String,
    _In_                     size_t    _Size,
    _In_opt_                 _locale_t _Locale
    );

__DEFINE_CPP_OVERLOAD_SECURE_FUNC_0_1(
    errno_t, _strlwr_s_l,
    _Prepost_z_ char,      _String,
    _In_opt_    _locale_t, _Locale
    )

__DEFINE_CPP_OVERLOAD_STANDARD_FUNC_0_1_EX(
    char*, __RETURN_POLICY_DST, _ACRTIMP, _strlwr_l, _strlwr_s_l,
    _Inout_updates_z_(_Size) char,
    _Inout_z_,               char,      _String,
    _In_opt_                 _locale_t, _Locale
    )

__DEFINE_CPP_OVERLOAD_SECURE_FUNC_0_2(
    errno_t, strncat_s,
    _Prepost_z_             char,        _Destination,
    _In_reads_or_z_(_Count) char const*, _Source,
    _In_                    size_t,      _Count
    )

__DEFINE_CPP_OVERLOAD_STANDARD_NFUNC_0_2_EX(
    char*, __RETURN_POLICY_DST, _ACRTIMP, strncat, strncat_s,
    _Inout_updates_z_(_Size)   char,
    _Inout_updates_z_(_Count), char,        _Destination,
    _In_reads_or_z_(_Count)    char const*, _Source,
    _In_                       size_t,      _Count
    )

_Check_return_
_ACRTIMP int __cdecl strncmp(
    _In_reads_or_z_(_MaxCount) char const* _Str1,
    _In_reads_or_z_(_MaxCount) char const* _Str2,
    _In_                       size_t      _MaxCount
    );

_Check_return_
_ACRTIMP int __cdecl _strnicmp(
    _In_reads_or_z_(_MaxCount) char const* _String1,
    _In_reads_or_z_(_MaxCount) char const* _String2,
    _In_                       size_t      _MaxCount
    );

_Check_return_
_ACRTIMP int __cdecl _strnicmp_l(
    _In_reads_or_z_(_MaxCount) char const* _String1,
    _In_reads_or_z_(_MaxCount) char const* _String2,
    _In_                       size_t      _MaxCount,
    _In_opt_                   _locale_t   _Locale
    );

_Check_return_
_ACRTIMP int __cdecl _strnicoll(
    _In_reads_or_z_(_MaxCount) char const* _String1,
    _In_reads_or_z_(_MaxCount) char const* _String2,
    _In_                       size_t      _MaxCount
    );

_Check_return_
_ACRTIMP int __cdecl _strnicoll_l(
    _In_reads_or_z_(_MaxCount) char const* _String1,
    _In_reads_or_z_(_MaxCount) char const* _String2,
    _In_                       size_t      _MaxCount,
    _In_opt_                   _locale_t   _Locale
    );

_Check_return_
_ACRTIMP int __cdecl _strncoll(
    _In_reads_or_z_(_MaxCount) char const* _String1,
    _In_reads_or_z_(_MaxCount) char const* _String2,
    _In_                       size_t      _MaxCount
    );

_Check_return_
_ACRTIMP int __cdecl _strncoll_l(
    _In_reads_or_z_(_MaxCount) char const* _String1,
    _In_reads_or_z_(_MaxCount) char const* _String2,
    _In_                       size_t      _MaxCount,
    _In_opt_                   _locale_t   _Locale
    );

_ACRTIMP size_t __cdecl __strncnt(
    _In_reads_or_z_(_Count) char const* _String,
    _In_                    size_t      _Count
    );

__DEFINE_CPP_OVERLOAD_SECURE_FUNC_0_2(
    errno_t, strncpy_s,
                            char,        _Destination,
    _In_reads_or_z_(_Count) char const*, _Source,
    _In_                    size_t,      _Count
    )

__DEFINE_CPP_OVERLOAD_STANDARD_NFUNC_0_2_EX(
    char*, __RETURN_POLICY_DST, _ACRTIMP, strncpy, strncpy_s,
    _Out_writes_z_(_Size)               char,
    _Out_writes_(_Count) _Post_maybez_, char,        _Destination,
    _In_reads_or_z_(_Count)             char const*, _Source,
    _In_                                size_t,      _Count
    )

_Check_return_
_When_(
    _MaxCount > _String_length_(_String),
    _Post_satisfies_(return == _String_length_(_String))
)
_When_(
    _MaxCount <= _String_length_(_String),
    _Post_satisfies_(return == _MaxCount)
)
_ACRTIMP size_t __cdecl strnlen(
    _In_reads_or_z_(_MaxCount) char const* _String,
    _In_                       size_t      _MaxCount
    );

#if __STDC_WANT_SECURE_LIB__ && !defined __midl

    _Check_return_
    _When_(
        _MaxCount > _String_length_(_String),
        _Post_satisfies_(return == _String_length_(_String))
    )
    _When_(
        _MaxCount <= _String_length_(_String),
        _Post_satisfies_(return == _MaxCount)
    )
    static __inline size_t __CRTDECL strnlen_s(
        _In_reads_or_z_(_MaxCount) char const* _String,
        _In_                       size_t      _MaxCount
        )
    {
        return _String == 0 ? 0 : strnlen(_String, _MaxCount);
    }

#endif

_Check_return_wat_
_ACRTIMP errno_t __cdecl _strnset_s(
    _Inout_updates_z_(_SizeInBytes) char*  _String,
    _In_                            size_t _SizeInBytes,
    _In_                            int    _Value,
    _In_                            size_t _MaxCount
    );

__DEFINE_CPP_OVERLOAD_SECURE_FUNC_0_2(
    errno_t, _strnset_s,
    _Prepost_z_ char,   _Destination,
    _In_        int,    _Value,
    _In_        size_t, _Count
    )

__DEFINE_CPP_OVERLOAD_STANDARD_NFUNC_0_2_EX(
    char*, __RETURN_POLICY_DST, _ACRTIMP, _strnset, _strnset_s,
    _Inout_updates_z_(_Size)   char,
    _Inout_updates_z_(_Count), char,   _Destination,
    _In_                       int,    _Value,
    _In_                       size_t, _Count
    )

_Check_return_
_ACRTIMP char _CONST_RETURN* __cdecl strpbrk(
    _In_z_ char const* _Str,
    _In_z_ char const* _Control
    );

_ACRTIMP char* __cdecl _strrev(
    _Inout_z_ char* _Str
    );

_Check_return_wat_
_ACRTIMP errno_t __cdecl _strset_s(
    _Inout_updates_z_(_DestinationSize) char*  _Destination,
    _In_                                size_t _DestinationSize,
    _In_                                int    _Value
    );

__DEFINE_CPP_OVERLOAD_SECURE_FUNC_0_1(
    errno_t, _strset_s,
    _Prepost_z_ char, _Destination,
    _In_        int,  _Value
    )

__DEFINE_CPP_OVERLOAD_STANDARD_FUNC_0_1(
    char*, __RETURN_POLICY_DST, __EMPTY_DECLSPEC, _strset,
    _Inout_z_, char, _Destination,
    _In_       int,  _Value
    )

_Check_return_
_ACRTIMP size_t __cdecl strspn(
    _In_z_ char const* _Str,
    _In_z_ char const* _Control
    );

_Check_return_ _CRT_INSECURE_DEPRECATE(strtok_s)
_ACRTIMP char* __cdecl strtok(
    _Inout_opt_z_ char*       _String,
    _In_z_        char const* _Delimiter
    );

_Check_return_wat_
_ACRTIMP errno_t __cdecl _strupr_s(
    _Inout_updates_z_(_Size) char*  _String,
    _In_                     size_t _Size
    );

__DEFINE_CPP_OVERLOAD_SECURE_FUNC_0_0(
    errno_t, _strupr_s,
    _Prepost_z_ char, _String
    )

__DEFINE_CPP_OVERLOAD_STANDARD_FUNC_0_0(
    char*, __RETURN_POLICY_DST, _ACRTIMP, _strupr,
    _Inout_z_, char, _String
    )

_Check_return_wat_
_ACRTIMP errno_t __cdecl _strupr_s_l(
    _Inout_updates_z_(_Size) char*     _String,
    _In_                     size_t    _Size,
    _In_opt_                 _locale_t _Locale
    );

__DEFINE_CPP_OVERLOAD_SECURE_FUNC_0_1(
    errno_t, _strupr_s_l,
    _Prepost_z_ char,      _String,
    _In_opt_    _locale_t, _Locale
    )

__DEFINE_CPP_OVERLOAD_STANDARD_FUNC_0_1_EX(
    char*, __RETURN_POLICY_DST, _ACRTIMP, _strupr_l, _strupr_s_l,
    _Inout_updates_z_(_Size) char,
    _Inout_z_,               char,      _String,
    _In_opt_                 _locale_t, _Locale
    )

_Success_(return < _MaxCount)
_Check_return_opt_
_ACRTIMP size_t __cdecl strxfrm(
    _Out_writes_opt_(_MaxCount) _Post_maybez_ char*       _Destination,
    _In_z_                                    char const* _Source,
    _In_ _In_range_(<=,_CRT_INT_MAX)          size_t      _MaxCount
    );

_Success_(return < _MaxCount)
_Check_return_opt_
_ACRTIMP size_t __cdecl _strxfrm_l(
    _Out_writes_opt_(_MaxCount) _Post_maybez_ char*       _Destination,
    _In_z_                                    char const* _Source,
    _In_ _In_range_(<=,_CRT_INT_MAX)          size_t      _MaxCount,
    _In_opt_                                  _locale_t   _Locale
    );



#ifdef __cplusplus
extern "C++"
{
    _Check_return_
    inline char* __CRTDECL strchr(_In_z_ char* const _String, _In_ int const _Ch)
    {
        return const_cast<char*>(strchr(static_cast<char const*>(_String), _Ch));
    }

    _Check_return_
    inline char* __CRTDECL strpbrk(_In_z_ char* const _String, _In_z_ char const* const _Control)
    {
        return const_cast<char*>(strpbrk(static_cast<char const*>(_String), _Control));
    }

    _Check_return_
    inline char* __CRTDECL strrchr(_In_z_ char* const _String, _In_ int const _Ch)
    {
        return const_cast<char*>(strrchr(static_cast<char const*>(_String), _Ch));
    }

    _Check_return_ _Ret_maybenull_
    inline char* __CRTDECL strstr(_In_z_ char* const _String, _In_z_ char const* const _SubString)
    {
        return const_cast<char*>(strstr(static_cast<char const*>(_String), _SubString));
    }
}
#endif // __cplusplus



#if _CRT_INTERNAL_NONSTDC_NAMES

    #if defined _DEBUG && defined _CRTDBG_MAP_ALLOC
        #pragma push_macro("strdup")
        #undef strdup
    #endif

    _Check_return_ _CRT_NONSTDC_DEPRECATE(_strdup)
    _ACRTIMP char* __cdecl strdup(
        _In_opt_z_ char const* _String
        );

    #if defined _DEBUG && defined _CRTDBG_MAP_ALLOC
        #pragma pop_macro("strdup")
    #endif

    // Declarations of functions defined in oldnames.lib:
    _Check_return_ _CRT_NONSTDC_DEPRECATE(_strcmpi)
    _ACRTIMP int __cdecl strcmpi(
        _In_z_ char const* _String1,
        _In_z_ char const* _String2
        );

    _Check_return_ _CRT_NONSTDC_DEPRECATE(_stricmp)
    _ACRTIMP int __cdecl stricmp(
        _In_z_ char const* _String1,
        _In_z_ char const* _String2
        );

    _CRT_NONSTDC_DEPRECATE(_strlwr)
    _ACRTIMP char* __cdecl strlwr(
        _Inout_z_ char* _String
        );

    _Check_return_ _CRT_NONSTDC_DEPRECATE(_strnicmp)
    _ACRTIMP int __cdecl strnicmp(
        _In_reads_or_z_(_MaxCount) char const* _String1,
        _In_reads_or_z_(_MaxCount) char const* _String2,
        _In_                       size_t      _MaxCount
        );

    _CRT_NONSTDC_DEPRECATE(_strnset)
    _ACRTIMP char* __cdecl strnset(
        _Inout_updates_z_(_MaxCount) char*  _String,
        _In_                         int    _Value,
        _In_                         size_t _MaxCount
        );

    _CRT_NONSTDC_DEPRECATE(_strrev)
    _ACRTIMP char* __cdecl strrev(
        _Inout_z_ char* _String
        );

    _CRT_NONSTDC_DEPRECATE(_strset)
    char* __cdecl strset(
        _Inout_z_ char* _String,
        _In_      int   _Value);

    _CRT_NONSTDC_DEPRECATE(_strupr)
    _ACRTIMP char* __cdecl strupr(
        _Inout_z_ char* _String
        );

#endif // _CRT_INTERNAL_NONSTDC_NAMES



_CRT_END_C_HEADER

#endif // !__midl