rid_hex/rid_hex.3

.TH Rid 3 "September 2017" "Version 1.0" "librid_hex API"
.SH NAME
rid_hex \- Rid hexadecimal string library.
.SH SYNOPSIS
.B #include <rid.h>
.br
.B #include <rid_hex.h>
.sp
Link with \fI\-lrid_hex\fP \fI\-lrid\fP and \fI\-lbsd\fP or `pkg-config --libs rid_hex`
.SH DESCRIPTION
A library to convert Rids to hexadecimal strings.
.sp
.SS Defines
.B RID_HEX_LEN
the length of a Rid as a hexadecimal string, it does not include the '\e0'. This would be the same value as calling
.B strlen ()
on a hexadecimal string representing a Rid.
.sp
.SS Types
.B Rid_hex
is a char array big enough for the hexadecimal string representation of a Rid provided by this library. It can hold 32 hexadecimal digits, each two representing one byte, plus a tailing '\e0'. It is defined as:
.sp
typedef char Rid_hex[33];
.sp
.B Rid_hex_path
is similar to
.BR Rid_hex ","
except a '/' is inserted after the first two digits. This is done to provide a relative path for using Rids as file names since some file systems have issues with having many files in a single directory. It is defined as:
.sp
typedef char Rid_hex_path[34];
.SS Functions
.BI "void rid_hex(char *" str ", const Rid " id ");"
.br
.BI "int rid_hex_parse(Rid " id ", const char *" str ");"
.br
.BI "void rid_hex_path(char *" path ", const Rid " id ");"
.sp
.B rid_hex ()
.RI "converts " id " to a hex string stored in " str "."
.sp
.B rid_hex_parse ()
.RI "converts " str " to binary stored in " id "."
.sp
.B rid_hex_path ()
.RI "converts " id " to a path suitable for a file name stored in " path "."
.SH "Return Value"
The function
.B rid_hex_parse ()
returns the number of characters parsed without error. On success this value is
.B RID_HEX_LEN
and on failure is less than
.BR RID_HEX_LEN "."
.SH EXAMPLES
.SS Creating a Rid path in a subdirectory
This can be done by passing a pointer to the last 33 bytes of a string to
.B Rid_hex_path
.RI "for the " path " argument. See the example program below:"
.sp
.nf
#include <rid.h>
#include <stdio.h>
#include <string.h>

#include <rid_hex.h>

/* define the directory we want to generate our Rid paths in */
#define DAT_DIR "dat/"
/* define the number of characters in DAT_DIR minus the '\e0' */
#define DAT_DIR_LEN (sizeof(DAT_DIR) - 1)

/* A type for a string big enough for our path */
typedef char Dir_path[DAT_DIR_LEN + sizeof(Rid_hex_path)];

int
main(int argc, char *argv[])
{
	Rid id;
	Dir_path dir_path;

	/* create a random rid */
	rid_set(id, NULL);
	/* set the dat/ part of the path */
	strcpy(dir_path, DAT_DIR);
	/* generate the rest of the path */
	rid_hex_path(dir_path + DAT_DIR_LEN, id);

	/* Now we can do anything we want with dir_path, it's just a string
	 * that looks something like "dat/41/7ed28b7db28473685f0c1dbf9f453f"
	 */

	printf("%s\en", dir_path);

	return 0;
}
.fi
.SS Converting, Parsing, and Comparing Rids
.nf
#include <rid.h>
#include <stdio.h>
#include <string.h>

#include <rid_hex.h>

int
main(int argc, char *argv[])
{
	Rid id1;
	Rid id2;
	Rid id3;
	Rid_hex str1;
	Rid_hex str2;

	/* set both id1 to a random value */
	rid_set(id1, NULL);

	/* copy id1 into id2 */
	rid_set(id2, id1);

	/* convert Rids to strings */
	rid_hex(str1, id1);
	rid_hex(str2, id2);

	/* and they will produce equal strings if they have the same value */
	if (!strcmp(str1, str2))
		printf("that only makes sense.\en");

	/* we can also get a Rid from a string */
	if (rid_hex_parse(id3, str1) < RID_HEX_LEN)
		printf("not printed since there is no error parsing.\en");

	if (!rid_cmp(id3, id1))
		printf("this will also be printed!\en");

	/* and that's all there is to it! */
	return 0;
}
.fi
.SH AUTHOR
Uladox (probably won't hex you)
.SH "AVAILABILITY AND SOURCE"
.B rid_hex
can be found in its repository at https://www.notabug.org/Uladox/rid_hex
.SH "SEE ALSO"
.BR rid (3)
.BR rid_fn85 (3)