1 /* 2 * SPDX-FileCopyrightText: Copyright (c) 2016-2020 NVIDIA CORPORATION & AFFILIATES. All rights reserved. 3 * SPDX-License-Identifier: MIT 4 * 5 * Permission is hereby granted, free of charge, to any person obtaining a 6 * copy of this software and associated documentation files (the "Software"), 7 * to deal in the Software without restriction, including without limitation 8 * the rights to use, copy, modify, merge, publish, distribute, sublicense, 9 * and/or sell copies of the Software, and to permit persons to whom the 10 * Software is furnished to do so, subject to the following conditions: 11 * 12 * The above copyright notice and this permission notice shall be included in 13 * all copies or substantial portions of the Software. 14 * 15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 18 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 20 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 21 * DEALINGS IN THE SOFTWARE. 22 */ 23 24 /** 25 * @file 26 * @brief String module public interface 27 */ 28 29 #ifndef _NVPORT_H_ 30 #error "This file cannot be included directly. Include nvport.h instead." 31 #endif 32 33 #ifndef _NVPORT_STRING_H_ 34 #define _NVPORT_STRING_H_ 35 36 /** 37 * @defgroup NVPORT_STRING String module 38 * 39 * @brief This module contains string functionality used by other modules. 40 * 41 * @{ 42 */ 43 44 /** 45 * @name Core Functions 46 * @{ 47 */ 48 49 /** 50 * @brief Compare two strings, character by character. 51 * 52 * Will only compare lengthBytes bytes. Strings are assumed to be at least that 53 * long. 54 * 55 * Strings are allowed to overlap, but in . 56 * 57 * @returns: 58 * - 0 if all bytes are equal 59 * - <0 if str1 is less than str2 for the first unequal byte. 60 * - >0 if str1 is greater than str2 for the first unequal byte. 61 * @par Undefined: 62 * Behavior is undefined if str1, str2 is NULL. <br> 63 */ 64 NvS32 portStringCompare(const char *str1, const char *str2, NvLength length); 65 /** 66 * @brief Copy a string. 67 * 68 * Will copy at most destSize bytes, stopping early if a null-terminator is found 69 * or if srcSize bytes are read from the source. 70 * 71 * Null character is always written at the end of the string. 72 * 73 * @param dest destination buffer, of at least destSize bytes (including null terminator). 74 * @param src source buffer, of at least srcSize bytes (including null terminator). 75 * 76 * @return size bytes copied successfully including null terminator, min(destSize, srcSize) 77 * 78 * @par Undefined: 79 * Number of allocated bytes in destination buffer are smaller than destSize. <br> 80 * Behavior is undefined if destination and source overlaps. <br> 81 */ 82 NvLength portStringCopy(char *dest, NvLength destSize, const char *src, NvLength srcSize); 83 /** 84 * @brief Concatenate two strings 85 * 86 * Will copy cat string after the end of str. Will copy only until str buffer is 87 * filled. str is assumed to point to a buffer of at least strSize bytes. 88 * 89 * Null character is always written at the end of the string. 90 * 91 * @return str if concatenation is succeeded. 92 * 93 * @par Undefined: 94 * Number of allocated bytes in destination buffer are smaller than destSize. <br> 95 * Behavior is undefined if destination and source overlaps. <br> 96 */ 97 char *portStringCat(char *str, NvLength strSize, const char *cat, NvLength catSize); 98 99 100 /** 101 * @brief Returns the index of the first NULL byte in the given string 102 * 103 */ 104 NvLength portStringLength(const char *str); 105 106 107 /** 108 * @brief Returns the index of the first NULL byte in the given string, it searches maxLength 109 * chars. If NULL byte is not found it returns maxLength. 110 * 111 */ 112 NvLength portStringLengthSafe(const char *str, NvLength maxLength); 113 114 115 /** 116 * @brief Converts a string from ASCII (8-bit) to UTF16 (16 bit) 117 * 118 * Can perform the conversion in place if dest == src. 119 * 120 * @returns The number of characters in destination buffer, without the null 121 * terminator (i.e. strlen(dest)) 122 */ 123 NvLength portStringConvertAsciiToUtf16(NvU16 *dest, NvLength destSize, const char *src, NvLength srcSize); 124 125 /** 126 * @brief Writes the hexadecimal string representation of the buffer 127 * 128 * @returns The number of characters in destination buffer, without the null 129 * terminator (i.e. strlen(str)) 130 */ 131 NvLength portStringBufferToHex(char *str, NvLength strSize, const NvU8 *buf, NvLength bufSize); 132 133 /** 134 * @brief Convert a binary buffer into readable group of hex digits 135 * 136 * @param groupCount - Number of groups 137 * @param groups - How to structure the groups (in number of hex chars) 138 * @param separator - Character to separate the groups 139 * 140 * For the traditional display of UUIDs, there would be five groups, {8,4,4,4,12} 141 * with the separator being '-'. 142 * 143 * @note odd numbers for group sizes are not supported, they will be rounded down 144 * 145 * @returns The number of characters in destination buffer, without the null 146 * terminator (i.e. strlen(str)) 147 */ 148 NvLength portStringBufferToHexGroups(char *str, NvLength strSize, const NvU8 *buf, NvLength bufSize, NvLength groupCount, const NvU32 *groups, const char *separator); 149 150 /// @} End core functions 151 152 /** 153 * @name Extended Functions 154 * @{ 155 */ 156 157 // Place extended functions here 158 159 /// @} End extended functions 160 161 #endif // _NVPORT_STRING_H_ 162 /// @} 163