string.h (8746B)
1/* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 20#ifndef GUAC_STRING_H 21#define GUAC_STRING_H 22 23/** 24 * Provides convenience functions for manipulating strings. 25 * 26 * @file string.h 27 */ 28 29#include <stddef.h> 30#include <string.h> 31 32/** 33 * Copies a limited number of bytes from the given source string to the given 34 * destination buffer. The resulting buffer will always be null-terminated, 35 * even if doing so means that the intended string is truncated, unless the 36 * destination buffer has no space available at all. As this function always 37 * returns the length of the string it tried to create (the length of the 38 * source string), whether truncation has occurred can be detected by comparing 39 * the return value against the size of the destination buffer. If the value 40 * returned is greater than or equal to the size of the destination buffer, then 41 * the string has been truncated. 42 * 43 * The source and destination buffers MAY NOT overlap. 44 * 45 * @param dest 46 * The buffer which should receive the contents of the source string. This 47 * buffer will always be null terminated unless zero bytes are available 48 * within the buffer. 49 * 50 * @param src 51 * The source string to copy into the destination buffer. This string MUST 52 * be null terminated. 53 * 54 * @param n 55 * The number of bytes available within the destination buffer. If this 56 * value is zero, no bytes will be written to the destination buffer, and 57 * the destination buffer may not be null terminated. In all other cases, 58 * the destination buffer will always be null terminated, even if doing 59 * so means that the copied data from the source string will be truncated. 60 * 61 * @return 62 * The length of the copied string (the source string) in bytes, excluding 63 * the null terminator. 64 */ 65size_t guac_strlcpy(char* restrict dest, const char* restrict src, size_t n); 66 67/** 68 * Appends the given source string after the end of the given destination 69 * string, writing at most the given number of bytes. Both the source and 70 * destination strings MUST be null-terminated. The resulting buffer will 71 * always be null-terminated, even if doing so means that the intended string 72 * is truncated, unless the destination buffer has no space available at all. 73 * As this function always returns the length of the string it tried to create 74 * (the length of destination and source strings added together), whether 75 * truncation has occurred can be detected by comparing the return value 76 * against the size of the destination buffer. If the value returned is greater 77 * than or equal to the size of the destination buffer, then the string has 78 * been truncated. 79 * 80 * The source and destination buffers MAY NOT overlap. 81 * 82 * @param dest 83 * The buffer which should be appended with the contents of the source 84 * string. This buffer MUST already be null-terminated and will always be 85 * null-terminated unless zero bytes are available within the buffer. 86 * 87 * As a safeguard against incorrectly-written code, in the event that the 88 * destination buffer is not null-terminated, this function will still stop 89 * before overrunning the buffer, instead behaving as if the length of the 90 * string in the buffer is exactly the size of the buffer. The destination 91 * buffer will remain untouched (and unterminated) in this case. 92 * 93 * @param src 94 * The source string to append to the the destination buffer. This string 95 * MUST be null-terminated. 96 * 97 * @param n 98 * The number of bytes available within the destination buffer. If this 99 * value is not greater than zero, no bytes will be written to the 100 * destination buffer, and the destination buffer may not be 101 * null-terminated. In all other cases, the destination buffer will always 102 * be null-terminated, even if doing so means that the copied data from the 103 * source string will be truncated. 104 * 105 * @return 106 * The length of the string this function tried to create (the lengths of 107 * the source and destination strings added together) in bytes, excluding 108 * the null terminator. 109 */ 110size_t guac_strlcat(char* restrict dest, const char* restrict src, size_t n); 111 112/** 113 * Search for the null-terminated string needle in the possibly null- 114 * terminated haystack, looking at no more than len bytes. 115 * 116 * @param haystack 117 * The string to search. It may or may not be null-terminated. Only the 118 * first len bytes are searched. 119 * 120 * @param needle 121 * The string to look for. It must be null-terminated. 122 * 123 * @param len 124 * The maximum number of bytes to examine in haystack. 125 * 126 * @return 127 * A pointer to the first instance of needle within haystack, or NULL if 128 * needle does not exist in haystack. If needle is the empty string, 129 * haystack is returned. 130 * 131 */ 132char* guac_strnstr(const char *haystack, const char *needle, size_t len); 133 134/** 135 * Duplicates the given string, returning a newly-allocated string containing 136 * the same contents. The provided string must be null-terminated. The size of 137 * the memory block for the newly-allocated string is only guaranteed to 138 * include enough space for the contents of the provided string, including null 139 * terminator. 140 * 141 * The pointer returned by guac_strdup() SHOULD be freed with a subsequent call 142 * to guac_mem_free(), but MAY instead be freed with a subsequent call to free(). 143 * 144 * This function behaves identically to standard strdup(), except that NULL 145 * will be returned if the provided string is NULL. 146 * 147 * @param str 148 * The string to duplicate as a newly-allocated string. 149 * 150 * @return 151 * A newly-allocated string containing identically the same content as the 152 * given string, or NULL if the given string was NULL. 153 */ 154char* guac_strdup(const char* str); 155 156/** 157 * Concatenates each of the given strings, separated by the given delimiter, 158 * storing the result within a destination buffer. The number of bytes written 159 * will be no more than the given number of bytes, and the destination buffer 160 * is guaranteed to be null-terminated, even if doing so means that one or more 161 * of the intended strings are truncated or omitted from the end of the result, 162 * unless the destination buffer has no space available at all. As this 163 * function always returns the length of the string it tried to create (the 164 * length of all source strings and all delimiters added together), whether 165 * truncation has occurred can be detected by comparing the return value 166 * against the size of the destination buffer. If the value returned is greater 167 * than or equal to the size of the destination buffer, then the string has 168 * been truncated. 169 * 170 * The source strings, delimiter string, and destination buffer MAY NOT 171 * overlap. 172 * 173 * @param dest 174 * The buffer which should receive the result of joining the given strings. 175 * This buffer will always be null terminated unless zero bytes are 176 * available within the buffer. 177 * 178 * @param elements 179 * The elements to concatenate together, separated by the given delimiter. 180 * Each element MUST be null-terminated. 181 * 182 * @param nmemb 183 * The number of elements within the elements array. 184 * 185 * @param delim 186 * The delimiter to include between each pair of elements. 187 * 188 * @param n 189 * The number of bytes available within the destination buffer. If this 190 * value is not greater than zero, no bytes will be written to the 191 * destination buffer, and the destination buffer may not be null 192 * terminated. In all other cases, the destination buffer will always be 193 * null terminated, even if doing so means that the result will be 194 * truncated. 195 * 196 * @return 197 * The length of the string this function tried to create (the length of 198 * all source strings and all delimiters added together) in bytes, 199 * excluding the null terminator. 200 */ 201size_t guac_strljoin(char* restrict dest, const char* restrict const* elements, 202 int nmemb, const char* restrict delim, size_t n); 203 204#endif 205