On 12/14/22 18:11, Alejandro Colomar wrote:
Hi Doug, On 12/14/22 17:36, Alejandro Colomar wrote:On 12/14/22 17:22, Douglas McIlroy wrote:chain copyThis term is never overtly defined. The definition might be inferred from, "To chain copy functions, they need to return a pointer to the end", but the problematic grammar of the sentence diverts attention from its content.Okay, I'll try to improve the wording in that paragraph; indeed that subsection intended to define the "chain copy" term.I'll hold on sending v5 to see if there is more feedback from others, but here's what I have for documenting the chain term:@@ -202,15 +192,36 @@ .SS Terms (and abbreviations) It is used as a sentinel value, to be able to truncate strings or character sequences instead of overrunning the containing buffer. -.\" ----- DESCRIPTION :: Copy, concatenate, and chain-copy ------------/ -.SS Copy, concatenate, and chain-copy +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: copy ------------/ +.TP +.I copy +This term is used when +the writing starts at the first element pointed to by +.IR dst . +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: catenate --------/ +.TP +.I catenate +This term is used when +a function first finds the terminating null byte in +.IR dst , +and then starts writing at that position. +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: chain -----------/ +.TP +.I chain +This term is used when +it's the programmer who provides a pointer to the +.IR end , +and the function starts writing at that location. +.IR dst .
@@ -213,6 +213,10 @@ .SS Terms (and abbreviations) .IR end , and the function starts writing at that location. .IR dst . +The function returns a pointer to the new +.I end +after the call, +so that the programmer can use it to chain such calls. .\" ----- DESCRIPTION :: Copy, catenate, and chain-copy ---------------/ .SS Copy, catenate, and chain-copy Originally, And this is for completeness. :)
+.\" ----- DESCRIPTION :: Copy, catenate, and chain-copy ---------------/ +.SS Copy, catenate, and chain-copy Originally, -there was a distinction between functions that copy and those that concatenate. +there was a distinction between functions that copy and those that catenate. However, newer functions that copy while allowing chaining cover both use cases with a single API. They are also algorithmically faster, since they don't need to search for the end of the existing string. -However, functions that concatenate have a much simpler use, +However, functions that catenate have a much simpler use, so if performance is not important, it can make sense to use them for improving readability. .PP Cheers, Alex
-- <http://www.alejandro-colomar.es/>
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
