cwk_path_join.md (3303B)
1 --- 2 title: cwk_path_join 3 description: Joins two paths together. 4 --- 5 6 _(since v1.0.0)_ 7 Joins two paths together. 8 9 ## Description 10 ```c 11 size_t cwk_path_join(const char *path_a, const char *path_b, char *buffer, 12 size_t buffer_size); 13 ``` 14 15 This function generates a new path by combining the two submitted paths. It will remove double separators, and unlike [cwk_path_get_absolute]({{ site.baseurl }}{% link reference/cwk_path_get_absolute.md %}) it permits the use of two relative paths to combine. The result will be written to a buffer, which might be truncated if the buffer is not large enough to hold the full path. However, the truncated result will always be null-terminated. The returned value is the amount of characters which the resulting path would take if it was not truncated (excluding the null-terminating character). 16 17 ## Parameters 18 * **path_a**: The first path which comes first. 19 * **path_b**: The second path which comes after the first. 20 * **buffer**: The buffer where the result will be written to. 21 * **buffer_size**: The size of the result buffer. 22 23 ## Return Value 24 Returns the total amount of characters of the full, combined path. 25 26 ## Outcomes 27 28 | Style | Path A | Path B | Result | 29 |---------|-----------------------|-------------------------|----------------------------------------| 30 | UNIX | ``hello/there`` | ``../world`` | ``hello/world`` | 31 | UNIX | ``/first`` | ``/second`` | ``/first/second`` | 32 | UNIX | ``hello`` | ``..`` | ``.`` | 33 | UNIX | ``hello/there`` | ``..`` | ``hello`` | 34 | UNIX | ``hello`` | ``there`` | ``hello/there`` | 35 | WINDOWS | ``this\`` | ``C:\..\..\is\a\test\`` | ``is\a\test`` | 36 | WINDOWS | ``C:\this\path`` | ``C:\is\a\test\`` | ``C:\this\path\C:\is\a\test`` | 37 | WINDOWS | ``C:\this\path`` | ``C:\..\is\a\test\`` | ``C:\this\path\is\a\test`` | 38 | WINDOWS | ``\\s1\unc\path`` | ``\\s2\unc\pa`` | ``\\s1\unc\pa\s2\unc\path`` | 39 40 ### Style 41 The style is automatically chosen during compile time, which is 42 UNIX for macOS and linux and WINDOWS for windows. You can change the style 43 using [cwk_path_set_style]({{ site.baseurl }}{% link reference/cwk_path_set_style.md %}). 44 45 ### Result 46 The **path_b** parameter will always be treated as a relative path, so even if 47 a driver letter is submitted on a windows style path, it will be treated as a 48 folder. 49 50 ## Example 51 ```c 52 #include <cwalk.h> 53 #include <stdio.h> 54 #include <stddef.h> 55 #include <stdlib.h> 56 57 int main(int argc, char *argv[]) 58 { 59 char buffer[FILENAME_MAX]; 60 61 cwk_path_join("hello/there", "../world", buffer, sizeof(buffer)); 62 printf("The combined path is: %s", buffer); 63 64 return EXIT_SUCCESS; 65 } 66 ``` 67 68 Ouput: 69 ``` 70 The combined path is: hello/world 71 ``` 72 73 ## Changelog 74 75 | Version | Description | 76 |------------|--------------------------------------------------------| 77 | **v1.0.0** | The function is introduced. |