cwalk/docs/reference/cwk_path_get_relative.md

title, description

title	description
cwk_path_get_relative	Generates a relative path based on a base.

(since v1.0.0)
Generates a relative path based on a base.

Description

size_t cwk_path_get_relative(const char *base_directory, const char *path,
  char *buffer, size_t buffer_size);

This function generates a relative path based on a base path and another path. It determines how to get to the submitted path, starting from the base directory. 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).

Parameters

• base_directory: The base path from which the relative path will start.
• path: The target path where the relative path will point to.
• buffer: The buffer where the result will be written to.
• buffer_size: The size of the result buffer.

Return Value

Returns the total amount of characters of the full path.

Outcomes

Style	Base	Path	Result
UNIX	/../../	/../../	.
UNIX	/path/same	/path/not_same/ho/..	../not_same
UNIX	/path/not_same/ho/..	/path/same	../same
UNIX	/path/same	/path/same/ho/..	.
UNIX	/path/same/ho/..	/path/same	.
UNIX	/path/same	/path/same	.
UNIX	/path/long/one	/path/long/one/two	two
UNIX	/path/long/one/two	/path/long/one	..
UNIX	./this/is/path_one	./this/is/path_two	../path_two
UNIX	/this/is/path_one	/this/is/path_two	../path_two
WINDOWS	C:/path/same	D:/path/same

Example

#include <cwalk.h>
#include <stdio.h>
#include <stddef.h>
#include <stdlib.h>

int main(int argc, char *argv[])
{
  char buffer[FILENAME_MAX];
  
  cwk_path_get_relative("/hello/there/", "/hello/world", buffer, sizeof(buffer));
  printf("The relative path is: %s", buffer);

  return EXIT_SUCCESS;
}

Ouput:

The relative path is: ../world

Changelog

Version	Description
v1.2.7	Fixed windows paths with forward slashes in root.
v1.2.5	Fixed calls with path without segments.
v1.2.5	Fixed calls with unequal roots in paths.
v1.0.0	The function is introduced.