123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146 |
- .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)
|