VirtualBox

Changeset 96160 in vbox for trunk/include


Ignore:
Timestamp:
Aug 12, 2022 11:06:25 AM (2 years ago)
Author:
vboxsync
Message:

iprt/string.h: Document RTStrToLongDoubleEx and friends, updated uBase/uBaseAndMaxLen docs on the RTStrTo[U]IntXx functions. bugref:10261

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/iprt/string.h

    r96152 r96160  
    28732873 * @param   pu64            Where to store the converted number. (optional)
    28742874 */
    2875 RTDECL(int) RTStrToUInt64Full(const char *pszValue, unsigned uBase, uint64_t *pu64);
     2875RTDECL(int) RTStrToUInt64Full(const char *pszValue, unsigned uBaseAndMaxLen, uint64_t *pu64);
    28762876
    28772877/**
    … …  
    29072907 * @param   pu32            Where to store the converted number. (optional)
    29082908 */
    2909 RTDECL(int) RTStrToUInt32Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint32_t *pu32);
     2909RTDECL(int) RTStrToUInt32Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, uint32_t *pu32);
    29102910
    29112911/**
    … …  
    29302930 * @param   pu32            Where to store the converted number. (optional)
    29312931 */
    2932 RTDECL(int) RTStrToUInt32Full(const char *pszValue, unsigned uBase, uint32_t *pu32);
     2932RTDECL(int) RTStrToUInt32Full(const char *pszValue, unsigned uBaseAndMaxLen, uint32_t *pu32);
    29332933
    29342934/**
    … …  
    29642964 * @param   pu16            Where to store the converted number. (optional)
    29652965 */
    2966 RTDECL(int) RTStrToUInt16Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint16_t *pu16);
     2966RTDECL(int) RTStrToUInt16Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, uint16_t *pu16);
    29672967
    29682968/**
    … …  
    29792979 * @retval  VERR_TRAILING_CHARS
    29802980 *
    2981  * @param   pszValue    Pointer to the string value.
    2982  * @param   uBase       The base of the representation used.
    2983  *                      If 0 the function will look for known prefixes before defaulting to 10.
    2984  * @param   pu16        Where to store the converted number. (optional)
    2985  */
    2986 RTDECL(int) RTStrToUInt16Full(const char *pszValue, unsigned uBase, uint16_t *pu16);
     2981 * @param   pszValue        Pointer to the string value.
     2982 * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
     2983 *                          upper 24 bits are the max length to parse.  If the base
     2984 *                          is zero the function will look for known prefixes before
     2985 *                          defaulting to 10.  A max length of zero means no length
     2986 *                          restriction.
     2987 * @param   pu16            Where to store the converted number. (optional)
     2988 */
     2989RTDECL(int) RTStrToUInt16Full(const char *pszValue, unsigned uBaseAndMaxLen, uint16_t *pu16);
    29872990
    29882991/**
    … …  
    30183021 * @param   pu8             Where to store the converted number. (optional)
    30193022 */
    3020 RTDECL(int) RTStrToUInt8Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint8_t *pu8);
     3023RTDECL(int) RTStrToUInt8Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, uint8_t *pu8);
    30213024
    30223025/**
    … …  
    30413044 * @param   pu8             Where to store the converted number. (optional)
    30423045 */
    3043 RTDECL(int) RTStrToUInt8Full(const char *pszValue, unsigned uBase, uint8_t *pu8);
     3046RTDECL(int) RTStrToUInt8Full(const char *pszValue, unsigned uBaseAndMaxLen, uint8_t *pu8);
    30443047
    30453048/**
    … …  
    30643067 * @retval  VERR_NO_DIGITS
    30653068 *
    3066  * @param   pszValue    Pointer to the string value.
    3067  * @param   ppszNext    Where to store the pointer to the first char following the number. (Optional)
    3068  * @param   uBase       The base of the representation used.
    3069  *                      If 0 the function will look for known prefixes before defaulting to 10.
    3070  * @param   pi64        Where to store the converted number. (optional)
    3071  */
    3072 RTDECL(int) RTStrToInt64Ex(const char *pszValue, char **ppszNext, unsigned uBase, int64_t *pi64);
     3069 * @param   pszValue        Pointer to the string value.
     3070 * @param   ppszNext        Where to store the pointer to the first char
     3071 *                          following the number. (Optional)
     3072 * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
     3073 *                          upper 24 bits are the max length to parse.  If the base
     3074 *                          is zero the function will look for known prefixes before
     3075 *                          defaulting to 10.  A max length of zero means no length
     3076 *                          restriction.
     3077 * @param   pi64            Where to store the converted number. (optional)
     3078 */
     3079RTDECL(int) RTStrToInt64Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, int64_t *pi64);
    30733080
    30743081/**
    … …  
    30843091 * @retval  VERR_NO_DIGITS
    30853092 *
    3086  * @param   pszValue    Pointer to the string value.
    3087  * @param   uBase       The base of the representation used.
    3088  *                      If 0 the function will look for known prefixes before defaulting to 10.
    3089  * @param   pi64        Where to store the converted number. (optional)
    3090  */
    3091 RTDECL(int) RTStrToInt64Full(const char *pszValue, unsigned uBase, int64_t *pi64);
     3093 * @param   pszValue        Pointer to the string value.
     3094 * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
     3095 *                          upper 24 bits are the max length to parse.  If the base
     3096 *                          is zero the function will look for known prefixes before
     3097 *                          defaulting to 10.  A max length of zero means no length
     3098 *                          restriction.
     3099 * @param   pi64            Where to store the converted number. (optional)
     3100 */
     3101RTDECL(int) RTStrToInt64Full(const char *pszValue, unsigned uBaseAndMaxLen, int64_t *pi64);
    30923102
    30933103/**
    … …  
    31123122 * @retval  VERR_NO_DIGITS
    31133123 *
    3114  * @param   pszValue    Pointer to the string value.
    3115  * @param   ppszNext    Where to store the pointer to the first char following the number. (Optional)
    3116  * @param   uBase       The base of the representation used.
    3117  *                      If 0 the function will look for known prefixes before defaulting to 10.
    3118  * @param   pi32        Where to store the converted number. (optional)
    3119  */
    3120 RTDECL(int) RTStrToInt32Ex(const char *pszValue, char **ppszNext, unsigned uBase, int32_t *pi32);
     3124 * @param   pszValue        Pointer to the string value.
     3125 * @param   ppszNext        Where to store the pointer to the first char
     3126 *                          following the number. (Optional)
     3127 * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
     3128 *                          upper 24 bits are the max length to parse.  If the base
     3129 *                          is zero the function will look for known prefixes before
     3130 *                          defaulting to 10.  A max length of zero means no length
     3131 *                          restriction.
     3132 * @param   pi32            Where  to store the converted number. (optional)
     3133 */
     3134RTDECL(int) RTStrToInt32Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, int32_t *pi32);
    31213135
    31223136/**
    … …  
    31323146 * @retval  VERR_NO_DIGITS
    31333147 *
    3134  * @param   pszValue    Pointer to the string value.
    3135  * @param   uBase       The base of the representation used.
    3136  *                      If 0 the function will look for known prefixes before defaulting to 10.
    3137  * @param   pi32        Where to store the converted number. (optional)
    3138  */
    3139 RTDECL(int) RTStrToInt32Full(const char *pszValue, unsigned uBase, int32_t *pi32);
     3148 * @param   pszValue        Pointer to the string value.
     3149 * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
     3150 *                          upper 24 bits are the max length to parse.  If the base
     3151 *                          is zero the function will look for known prefixes before
     3152 *                          defaulting to 10.  A max length of zero means no length
     3153 *                          restriction.
     3154 * @param   pi32            Where to store the converted number. (optional)
     3155 */
     3156RTDECL(int) RTStrToInt32Full(const char *pszValue, unsigned uBaseAndMaxLen, int32_t *pi32);
    31403157
    31413158/**
    … …  
    31603177 * @retval  VERR_NO_DIGITS
    31613178 *
    3162  * @param   pszValue    Pointer to the string value.
    3163  * @param   ppszNext    Where to store the pointer to the first char following the number. (Optional)
    3164  * @param   uBase       The base of the representation used.
    3165  *                      If 0 the function will look for known prefixes before defaulting to 10.
    3166  * @param   pi16        Where to store the converted number. (optional)
    3167  */
    3168 RTDECL(int) RTStrToInt16Ex(const char *pszValue, char **ppszNext, unsigned uBase, int16_t *pi16);
     3179 * @param   pszValue        Pointer to the string value.
     3180 * @param   ppszNext        Where to store the pointer to the first char
     3181 *                          following the number. (Optional)
     3182 * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
     3183 *                          upper 24 bits are the max length to parse.  If the base
     3184 *                          is zero the function will look for known prefixes before
     3185 *                          defaulting to 10.  A max length of zero means no length
     3186 *                          restriction.
     3187 * @param   pi16            Where to store the converted number. (optional)
     3188 */
     3189RTDECL(int) RTStrToInt16Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, int16_t *pi16);
    31693190
    31703191/**
    … …  
    31803201 * @retval  VERR_NO_DIGITS
    31813202 *
    3182  * @param   pszValue    Pointer to the string value.
    3183  * @param   uBase       The base of the representation used.
    3184  *                      If 0 the function will look for known prefixes before defaulting to 10.
    3185  * @param   pi16        Where to store the converted number. (optional)
    3186  */
    3187 RTDECL(int) RTStrToInt16Full(const char *pszValue, unsigned uBase, int16_t *pi16);
     3203 * @param   pszValue        Pointer to the string value.
     3204 * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
     3205 *                          upper 24 bits are the max length to parse.  If the base
     3206 *                          is zero the function will look for known prefixes before
     3207 *                          defaulting to 10.  A max length of zero means no length
     3208 *                          restriction.
     3209 * @param   pi16            Where to store the converted number. (optional)
     3210 */
     3211RTDECL(int) RTStrToInt16Full(const char *pszValue, unsigned uBaseAndMaxLen, int16_t *pi16);
    31883212
    31893213/**
    … …  
    32083232 * @retval  VERR_NO_DIGITS
    32093233 *
    3210  * @param   pszValue    Pointer to the string value.
    3211  * @param   ppszNext    Where to store the pointer to the first char following the number. (Optional)
    3212  * @param   uBase       The base of the representation used.
    3213  *                      If 0 the function will look for known prefixes before defaulting to 10.
    3214  * @param   pi8         Where to store the converted number. (optional)
    3215  */
    3216 RTDECL(int) RTStrToInt8Ex(const char *pszValue, char **ppszNext, unsigned uBase, int8_t *pi8);
     3234 * @param   pszValue        Pointer to the string value.
     3235 * @param   ppszNext        Where to store the pointer to the first char
     3236 *                          following the number. (Optional)
     3237 * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
     3238 *                          upper 24 bits are the max length to parse.  If the base
     3239 *                          is zero the function will look for known prefixes before
     3240 *                          defaulting to 10.  A max length of zero means no length
     3241 *                          restriction.
     3242 * @param   pi8             Where to store the converted number. (optional)
     3243 */
     3244RTDECL(int) RTStrToInt8Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, int8_t *pi8);
    32173245
    32183246/**
    … …  
    32283256 * @retval  VERR_NO_DIGITS
    32293257 *
    3230  * @param   pszValue    Pointer to the string value.
    3231  * @param   uBase       The base of the representation used.
    3232  *                      If 0 the function will look for known prefixes before defaulting to 10.
    3233  * @param   pi8         Where to store the converted number. (optional)
    3234  */
    3235 RTDECL(int) RTStrToInt8Full(const char *pszValue, unsigned uBase, int8_t *pi8);
     3258 * @param   pszValue        Pointer to the string value.
     3259 * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
     3260 *                          upper 24 bits are the max length to parse.  If the base
     3261 *                          is zero the function will look for known prefixes before
     3262 *                          defaulting to 10.  A max length of zero means no length
     3263 *                          restriction.
     3264 * @param   pi8             Where to store the converted number. (optional)
     3265 */
     3266RTDECL(int) RTStrToInt8Full(const char *pszValue, unsigned uBaseAndMaxLen, int8_t *pi8);
    32363267
    32373268/**
    … …  
    32443275 */
    32453276RTDECL(int8_t) RTStrToInt8(const char *pszValue);
     3277
     3278
     3279/**
     3280 * Converts a string to long double floating point, extended edition.
     3281 *
     3282 * Please note that long double can be double precision, extended precision, or
     3283 * quad precision floating point depending on the platform and architecture. See
     3284 * RT_COMPILER_WITH_128BIT_LONG_DOUBLE and RT_COMPILER_WITH_80BIT_LONG_DOUBLE.
     3285 *
     3286 * @returns IPRT status code.
     3287 * @retval  VERR_NO_DIGITS if no valid digits found.
     3288 * @retval  VWRN_FLOAT_UNDERFLOW on underflow with denormal/subnormal return
     3289 *          value
     3290 * @retval  VERR_FLOAT_UNDERFLOW on underflow, value set to +/- zero.
     3291 * @retval  VERR_FLOAT_OVERFLOW on overflow, value set to +/- infinity.
     3292 * @retval  VWRN_TRAILING_CHARS
     3293 * @retval  VWRN_TRAILING_SPACES
     3294 *
     3295 * @param   pszValue    The string to parse.
     3296 * @param   ppszNext    Where to store the pointer to the first char following
     3297 *                      the number.  Optional.
     3298 * @param   cchMax      Max number of character to parse.  Zero means unlimited.
     3299 * @param   plrd        Where to return the number.  Optional.
     3300 *
     3301 * @note    This code isn't entirely perfect yet.  It could exhibit rounding
     3302 *          differences compared to strtold & the compiler, and extreme value
     3303 *          may overflow/underflow prematurely depending on the build config.
     3304 */
     3305RTDECL(int) RTStrToLongDoubleEx(const char *pszValue, char **ppszNext, size_t cchMax, long double *plrd);
     3306
     3307/**
     3308 * Converts a string to double precision floating point, extended edition.
     3309 *
     3310 * @returns IPRT status code.
     3311 * @retval  VERR_NO_DIGITS if no valid digits found.
     3312 * @retval  VWRN_FLOAT_UNDERFLOW on underflow with denormal/subnormal return
     3313 *          value
     3314 * @retval  VERR_FLOAT_UNDERFLOW on underflow, value set to +/- zero.
     3315 * @retval  VERR_FLOAT_OVERFLOW on overflow, value set to +/- infinity.
     3316 * @retval  VWRN_TRAILING_CHARS
     3317 * @retval  VWRN_TRAILING_SPACES
     3318 *
     3319 * @param   pszValue    The string to parse.
     3320 * @param   ppszNext    Where to store the pointer to the first char following
     3321 *                      the number.  Optional.
     3322 * @param   cchMax      Max number of character to parse.  Zero means unlimited.
     3323 * @param   plrd        Where to return the number.  Optional.
     3324 *
     3325 * @note    This code isn't entirely perfect yet.  It could exhibit rounding
     3326 *          differences compared to strtold & the compiler, and extreme value
     3327 *          may overflow/underflow prematurely depending on the build config.
     3328 */
     3329RTDECL(int) RTStrToDoubleEx(const char *pszValue, char **ppszNext, size_t cchMax, double *prd);
     3330
     3331/**
     3332 * Converts a string to single precision floating point, extended edition.
     3333 *
     3334 * @returns IPRT status code.
     3335 * @retval  VERR_NO_DIGITS if no valid digits found.
     3336 * @retval  VWRN_FLOAT_UNDERFLOW on underflow with denormal/subnormal return
     3337 *          value
     3338 * @retval  VERR_FLOAT_UNDERFLOW on underflow, value set to +/- zero.
     3339 * @retval  VERR_FLOAT_OVERFLOW on overflow, value set to +/- infinity.
     3340 * @retval  VWRN_TRAILING_CHARS
     3341 * @retval  VWRN_TRAILING_SPACES
     3342 *
     3343 * @param   pszValue    The string to parse.
     3344 * @param   ppszNext    Where to store the pointer to the first char following
     3345 *                      the number.  Optional.
     3346 * @param   cchMax      Max number of character to parse.  Zero means unlimited.
     3347 * @param   plrd        Where to return the number.  Optional.
     3348 *
     3349 * @note    This code isn't entirely perfect yet.  It could exhibit rounding
     3350 *          differences compared to strtold & the compiler, and extreme value
     3351 *          may overflow/underflow prematurely depending on the build config.
     3352 */
     3353RTDECL(int) RTStrToFloatEx(const char *pszValue, char **ppszNext, size_t cchMax, float *pr);
     3354
    32463355
    32473356/**
    … …  
    33243433RTDECL(int) RTStrConvertHexBytesEx(char const *pszHex, void *pv, size_t cb, uint32_t fFlags,
    33253434                                   const char **ppszNext, size_t *pcbReturned);
    3326 
    3327 
    3328 RTDECL(int) RTStrToLongDoubleEx(const char *pszValue, char **ppszNext, size_t cchMax, long double *plrd);
    3329 RTDECL(int) RTStrToDoubleEx(const char *pszValue, char **ppszNext, size_t cchMax, double *prd);
    3330 RTDECL(int) RTStrToFloatEx(const char *pszValue, char **ppszNext, size_t cchMax, float *pr);
    33313435
    33323436/** @} */
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette