commit f6445e59a70e9378fe5f08052302d12928cfa8d0
parent a117fa3478e9eadf15d019dd1a382f8466fffcca
Author: ssnf <ssnf@ssnf.xyz>
Date: Fri, 11 Jul 2025 00:57:01 +0000
add libstr manpage
Diffstat:
2 files changed, 312 insertions(+), 0 deletions(-)
diff --git a/man/man3/INDEX b/man/man3/INDEX
@@ -1171,6 +1171,23 @@ s_restart string.3
s_terminate string.3
s_tolower string.3
s_unique string.3
+Str str.3
+Strn str.3
+Straddc str.3
+Stradds str.3
+Strclose str.3
+Strdelc str.3
+Strdelete str.3
+Strdup str.3
+Strgetf str.3
+Strgets str.3
+Strinit str.3
+Strinsert str.3
+Strinsure str.3
+Strprint str.3
+Strtok str.3
+Strzero str.3
+str str.3
string string.3
runestringnwidth stringsize.3
runestringsize stringsize.3
diff --git a/man/man3/str.3 b/man/man3/str.3
@@ -0,0 +1,295 @@
+.TH STR 3
+.SH NAME
+Str, Strn, Straddc, Stradds, Strclose, Strdelc, Strdelete, Strdup, Strgetf, Strgets, Strinit, Strinsert, Strinsure, Strprint, Strtok, Strzero \- dynamic string library
+.SH SYNOPSIS
+.B #include <u.h>
+.br
+.B #include <libc.h>
+.br
+.B #include <str.h>
+.PP
+.ft L
+.nf
+.ta \w'\fL 'u +\w'\fLulong 'u
+typedef struct {
+ char *s;
+ ulong n;
+ ulong size;
+} String;
+.fi
+.PP
+.ta \w'\fLString 'u
+.B
+String Str(char *s)
+.PP
+.B
+String Strn(char *s, ulong n)
+.PP
+.B
+void Straddc(String *p, int c)
+.PP
+.B
+void Stradds(String *p, String s)
+.PP
+.B
+void Strclose(String *s)
+.PP
+.B
+void Strdelc(String *s)
+.PP
+.B
+void Strdelete(String *s, Posn p0, Posn p1)
+.PP
+.B
+void Strdup(String *p, String s)
+.PP
+.B
+void Strgetf(String *s, int fd)
+.PP
+.B
+int Strgets(String *s, Biobuf *b)
+.PP
+.B
+void Strinit(String *s)
+.PP
+.B
+void Strinsert(String *s, String t, Posn p0)
+.PP
+.B
+void Strinsure(String *s, ulong n)
+.PP
+.B
+int Strprint(String *s, char *fmt, ...)
+.PP
+.B
+void Strtok(String *s, char *str, char *sep, char **last)
+.PP
+.B
+void Strzero(String *s)
+.SH DESCRIPTION
+This library provides a dynamic string implementation that is
+mutually exclusive with Plan 9's standard libString.
+It offers a simpler, more lightweight alternative focused on ease of use.
+A
+.B String
+contains a pointer to the string data, its current length, and its allocated size.
+.SS "Comparison with libString"
+This library differs from Plan 9's standard libString in several key ways:
+.IP \(bu
+.B No locking:
+libString includes locking mechanisms for thread safety, while this library omits them for simplicity.
+.IP \(bu
+.B Stack allocation:
+.I Str
+and
+.I Strn
+create stack-allocated strings that reference existing data,
+while libString requires heap allocation for all strings.
+.IP \(bu
+.B Direct formatting:
+.I Strprint
+provides direct formatted output using
+.IR vsmprint ,
+while libString requires separate formatting steps.
+.IP \(bu
+.B Simpler structure:
+Uses a 3-field structure (s, n, size) compared to libString's
+6-field structure with reference counting and locking.
+.PP
+Both libraries provide similar Biobuf integration for reading operations.
+.PP
+.I Str
+creates a
+.B String
+from a null-terminated C string.
+The resulting string references the original data and should not be modified.
+.PP
+.I Strn
+creates a
+.B String
+from the first
+.I n
+characters of a C string.
+The resulting string references the original data and should not be modified.
+.PP
+.I Strinit
+initializes a
+.B String
+for use as a dynamic string.
+The string is initially empty but has space allocated for growth.
+.PP
+.I Strdup
+copies string
+.I s
+into string
+.IR p ,
+which must be initialized.
+Any existing content in
+.I p
+is replaced.
+.PP
+.I Straddc
+appends character
+.I c
+to string
+.IR p .
+The string grows automatically if necessary.
+.PP
+.I Stradds
+appends string
+.I s
+to string
+.IR p .
+The string grows automatically if necessary.
+.PP
+.I Strinsert
+inserts string
+.I t
+into string
+.I s
+at position
+.IR p .
+Characters after position
+.I p
+are shifted to make room.
+.PP
+.I Strdelete
+deletes characters from position
+.I p0
+to position
+.I p1
+(exclusive) from string
+.IR s .
+Characters after the deleted range are shifted down.
+.PP
+.I Strdelc
+deletes the last character from string
+.IR s .
+If the string is empty, it does nothing.
+.PP
+.I Strinsure
+ensures that string
+.I s
+has space for at least
+.I n
+characters.
+This can be used to preallocate space for better performance.
+.PP
+.I Strprint
+appends formatted text to string
+.I s
+using the same format specifiers as
+.IR print (3).
+It returns the number of characters added.
+.PP
+.I Strgetf
+reads the entire contents of file descriptor
+.I fd
+into string
+.IR s .
+Any existing content is replaced.
+.PP
+.I Strgets
+reads a line from
+.I Biobuf
+.I b
+into string
+.IR s .
+The newline character is included if present.
+It returns 1 on success, 0 on end of file, and -1 on error.
+.PP
+.I Strtok
+tokenizes string
+.I str
+using separator characters in
+.IR sep .
+The first token is stored in
+.I s
+and
+.I last
+is set to point to the remaining string.
+.PP
+.I Strzero
+empties string
+.I s
+but retains its allocated space.
+.PP
+.I Strclose
+frees the memory used by string
+.I s
+and resets it to empty.
+.SH EXAMPLES
+.PP
+Basic string operations:
+.IP
+.EX
+String s;
+
+Strinit(&s);
+Stradds(&s, Str("Hello"));
+Straddc(&s, ' ');
+Stradds(&s, Str("World"));
+print("%s\en", s.s);
+Strclose(&s);
+.EE
+.PP
+Reading a file:
+.IP
+.EX
+String s;
+int fd;
+
+Strinit(&s);
+fd = open("file.txt", OREAD);
+if(fd >= 0) {
+ Strgetf(&s, fd);
+ close(fd);
+ print("File contents: %s\en", s.s);
+}
+Strclose(&s);
+.EE
+.PP
+String formatting:
+.IP
+.EX
+String s;
+
+Strinit(&s);
+Strprint(&s, "Number: %d, String: %s", 42, "test");
+print("%s\en", s.s);
+Strclose(&s);
+.EE
+.PP
+String editing:
+.IP
+.EX
+String s;
+
+Strinit(&s);
+Stradds(&s, Str("Hello World"));
+Strdelete(&s, 5, 6); /* Delete space */
+Strinsert(&s, Str("_"), 5);
+print("%s\en", s.s); /* Prints: Hello_World */
+Strclose(&s);
+.EE
+.SH SOURCE
+.B \*9/src/libstr
+.SH SEE ALSO
+.MR bio (3) ,
+.MR print (3) ,
+.MR string (3)
+.SH DIAGNOSTICS
+Functions call
+.I sysfatal
+if memory allocation fails.
+.SH NOTES
+Strings created with
+.I Str
+and
+.I Strn
+reference the original data and should not be modified
+or passed to
+.IR Strclose .
+Use
+.I Strdup
+to create a modifiable copy.
