From 810e16de6894532c2b71eec1b509fb99cebeaf6c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fredrik=20H=C3=BCbinette=20=28Hubbe=29?= <hubbe@hubbe.net>
Date: Sat, 12 Oct 1996 19:20:28 +0200
Subject: [PATCH] new documenation for struct pike_string
Rev: doc/internal/strings/add_shared_strings:1.1
Rev: doc/internal/strings/begin_shared_string:1.1
Rev: doc/internal/strings/binary_findstring:1.1
Rev: doc/internal/strings/end_shared_string:1.1
Rev: doc/internal/strings/findstring:1.1
Rev: doc/internal/strings/free_string:1.1
Rev: doc/internal/strings/make_shared_binary_string:1.1
Rev: doc/internal/strings/make_shared_string:1.1
Rev: doc/internal/strings/my_strcmp:1.1
Rev: doc/internal/strings/pike_string:1.1
Rev: doc/internal/strings/push_string:1.1
Rev: doc/internal/strings/string_replace:1.1
---
doc/internal/strings/add_shared_strings | 19 +++++++++++
doc/internal/strings/begin_shared_string | 18 +++++++++++
doc/internal/strings/binary_findstring | 18 +++++++++++
doc/internal/strings/end_shared_string | 32 +++++++++++++++++++
doc/internal/strings/findstring | 18 +++++++++++
doc/internal/strings/free_string | 18 +++++++++++
.../strings/make_shared_binary_string | 19 +++++++++++
doc/internal/strings/make_shared_string | 17 ++++++++++
doc/internal/strings/my_strcmp | 19 +++++++++++
doc/internal/strings/pike_string | 18 +++++++++++
doc/internal/strings/push_string | 20 ++++++++++++
doc/internal/strings/string_replace | 17 ++++++++++
12 files changed, 233 insertions(+)
create mode 100644 doc/internal/strings/add_shared_strings
create mode 100644 doc/internal/strings/begin_shared_string
create mode 100644 doc/internal/strings/binary_findstring
create mode 100644 doc/internal/strings/end_shared_string
create mode 100644 doc/internal/strings/findstring
create mode 100644 doc/internal/strings/free_string
create mode 100644 doc/internal/strings/make_shared_binary_string
create mode 100644 doc/internal/strings/make_shared_string
create mode 100644 doc/internal/strings/my_strcmp
create mode 100644 doc/internal/strings/pike_string
create mode 100644 doc/internal/strings/push_string
create mode 100644 doc/internal/strings/string_replace
diff --git a/doc/internal/strings/add_shared_strings b/doc/internal/strings/add_shared_strings
new file mode 100644
index 0000000000..7a08a2c3a3
--- /dev/null
+++ b/doc/internal/strings/add_shared_strings
@@ -0,0 +1,19 @@
+NAME
+ add_shared_strings - add two pike strings
+
+SYNTAX
+ #include "stralloc.h"
+
+ struct pike_string *add_shared_strings(struct pike_string *a,
+ struct pike_string *b);
+
+DESCRIPTION
+ This function builds the string a+b, that is the string a with the
+ string b appended to it. Note that the string returned will have
+ an extra reference.
+
+KEYWORDS
+ pike_string
+
+SEE ALSO
+ begin_shared_string, make_shared_string
\ No newline at end of file
diff --git a/doc/internal/strings/begin_shared_string b/doc/internal/strings/begin_shared_string
new file mode 100644
index 0000000000..52148da8d9
--- /dev/null
+++ b/doc/internal/strings/begin_shared_string
@@ -0,0 +1,18 @@
+NAME
+ begin_shared_string - allocate space for a shared string
+
+SYNTAX
+ #include "stralloc.h"
+
+ struct pike_string *begin_shared_string(INT32 len);
+
+DESCRIPTION
+ This function allocates space for a shared string of length 'len'.
+ You should then MEMCPY 'len' bytes into the s->str. (s being the
+ returned value) And then call end_shared_string.
+
+KEYWORDS
+ pike_string
+
+SEE ALSO
+ end_shared_string, make_shared_string
diff --git a/doc/internal/strings/binary_findstring b/doc/internal/strings/binary_findstring
new file mode 100644
index 0000000000..0f34b20925
--- /dev/null
+++ b/doc/internal/strings/binary_findstring
@@ -0,0 +1,18 @@
+NAME
+ binary_findstring - find a string
+
+SYNTAX
+ #include "stralloc.h"
+
+ struct pike_string *binary_findstring(char *str, INT32 length);
+
+DESCRIPTION
+ This function looks for the 'str' with length 'len' in the
+ global hash table. It returns the shared string if found, otherwise
+ zero. It does not increase/decrease the references to the string.
+
+KEYWORDS
+ pike_string
+
+SEE ALSO
+ findstring
diff --git a/doc/internal/strings/end_shared_string b/doc/internal/strings/end_shared_string
new file mode 100644
index 0000000000..100ac2cc2c
--- /dev/null
+++ b/doc/internal/strings/end_shared_string
@@ -0,0 +1,32 @@
+NAME
+ end_shared_string - link a shared string into the hashtable
+
+SYNTAX
+ #include "stralloc.h"
+
+ struct pike_string *end_shared_string(struct pike_string *p);
+
+DESCRIPTION
+ This function the prepared output from a begin_shared_string and
+ links the string into the hash table. If an identical string is
+ already present in the hash table, p is freed and that string is
+ returned instead. The returned string will have one extra reference
+ added.
+
+EXAMPLE
+ #include "global.h"
+ #include "stralloc.h"
+
+ struct pike_string *mkcharstring(int ch)
+ {
+ struct pike_string *ret;
+ ret=begin_shared_string(1);
+ ret->str[0]=ch;
+ return end_shared_string(ret);
+ }
+
+KEYWORDS
+ pike_string
+
+SEE ALSO
+ begin_shared_string
diff --git a/doc/internal/strings/findstring b/doc/internal/strings/findstring
new file mode 100644
index 0000000000..dbd299a6d7
--- /dev/null
+++ b/doc/internal/strings/findstring
@@ -0,0 +1,18 @@
+NAME
+ findstring - find a string
+
+SYNTAX
+ #include "stralloc.h"
+
+ struct pike_string *findstring(char *str);
+
+DESCRIPTION
+ This function looks for the null terminated C string 'str' in the
+ global hash table. It returns the shared string if found, otherwise
+ zero. It does not increase/decrease the references to the string.
+
+KEYWORDS
+ pike_string
+
+SEE ALSO
+ make_shared_string, binary_findstring
diff --git a/doc/internal/strings/free_string b/doc/internal/strings/free_string
new file mode 100644
index 0000000000..918c8811f2
--- /dev/null
+++ b/doc/internal/strings/free_string
@@ -0,0 +1,18 @@
+NAME
+ free_string - free a pike string
+
+SYNTAX
+ #include "stralloc.h"
+
+ void free_string(struct pike_string *p)
+
+DESCRIPITON
+ This function frees the string 'p'. What it actually does is that it
+ decreases the reference count of 'p' and frees the memory reserved
+ for it if the refereneces reach zero.
+
+NOTA BENE
+ free_string is actually a macro
+
+KEYWORDS
+ pike_string
diff --git a/doc/internal/strings/make_shared_binary_string b/doc/internal/strings/make_shared_binary_string
new file mode 100644
index 0000000000..a455237f9a
--- /dev/null
+++ b/doc/internal/strings/make_shared_binary_string
@@ -0,0 +1,19 @@
+NAME
+ make_shared_binary_string - make a shared string
+
+SYNTAX
+ #include "stralloc.h"
+
+ struct pike_string *make_shared_binary_string(const char *str, int len);
+
+DESCRIPTION
+ This function makes a shared string from the memory area beginning
+ at 'str' and ends at str+len. The returned string will have one
+ extra reference.
+
+KEYWORDS
+ pike_string
+
+SEE ALSO
+ make_shared_string, begin_shared_string, push_string,
+ free_string
diff --git a/doc/internal/strings/make_shared_string b/doc/internal/strings/make_shared_string
new file mode 100644
index 0000000000..121459344b
--- /dev/null
+++ b/doc/internal/strings/make_shared_string
@@ -0,0 +1,17 @@
+NAME
+ make_shared_binary_string - make a shared string
+
+SYNTAX
+ #include "stralloc.h"
+
+ struct pike_string *make_shared_string(const char *str);
+
+DESCRIPTION
+ This function does the same thing as make_shared_binary_string, but
+ expects a zero terminated string instead.
+
+KEYWORDS
+ pike_string
+
+SEE ALSO
+ make_shared_binary_string
diff --git a/doc/internal/strings/my_strcmp b/doc/internal/strings/my_strcmp
new file mode 100644
index 0000000000..d38b724f66
--- /dev/null
+++ b/doc/internal/strings/my_strcmp
@@ -0,0 +1,19 @@
+NAME
+ my_strcmp - my own strcmp function
+
+SYNTAX
+ #include "stralloc.h"
+
+ int my_strcmp(struct pike_string *a, struct pike_string *b)
+
+DESCRIPTION
+ This function compares two pike strings and takes locales into
+ account if the system supports locales. It returns zero if the
+ strings are the same, a number greater than zero zero if 'a'
+ is greater than 'b', and a number below zero otherwise.
+
+KEYWORDS
+ pike_string
+
+SEE ALSO
+ make_shared_string
\ No newline at end of file
diff --git a/doc/internal/strings/pike_string b/doc/internal/strings/pike_string
new file mode 100644
index 0000000000..1d095ef570
--- /dev/null
+++ b/doc/internal/strings/pike_string
@@ -0,0 +1,18 @@
+NAME
+ pike_string - internal pike shared strings
+
+DESCRIPTION
+ This is the internal type for representing pike strings. They have
+ ref counts and they are shared though a global hash table. The C
+ type is a struct pike_string that has two public members: str and
+ len. str is an array of char which contain the actual string. It
+ is guaranteed that the string is null terminated, but the string
+ can also contain zeroes before the end. len is of course the
+ length of the string. Since strings are shared you may _never_
+ modify the contents of a string, except for adding/subtracting
+ references when approperiate. The only exception to this is when
+ creating a new shared string with begin_shared_string which has
+ not yet been linked to the hash table with end_shared_string.
+
+KEYWORD
+ internals
diff --git a/doc/internal/strings/push_string b/doc/internal/strings/push_string
new file mode 100644
index 0000000000..0b0773c04d
--- /dev/null
+++ b/doc/internal/strings/push_string
@@ -0,0 +1,20 @@
+NAME
+ push_string - push a string on the pike stack
+
+SYNTAX
+ #include "interpret.h"
+
+ void push_string(struct pike_string *p)
+
+DESCRIPTION
+ This function pushes the string p on the pike stack. Note that this
+ function does _not_ add any extra references to 'p'. Most functions
+ that create shared strings give one extra reference to them though.
+ If you get your string from a function that does not add extra
+ references you will have to add a reference manually.
+
+NOTA BENE
+ push_string is actually a macro
+
+KEYWORDS
+ pike_string
diff --git a/doc/internal/strings/string_replace b/doc/internal/strings/string_replace
new file mode 100644
index 0000000000..6532498aa2
--- /dev/null
+++ b/doc/internal/strings/string_replace
@@ -0,0 +1,17 @@
+NAME
+ string_replace - do string replacements
+
+SYNTAX
+ #include "stralloc.h"
+
+ struct pike_string *string_replace(struct pike_string *str,
+ struct pike_string *from,
+ struct pike_string *to);
+
+DESCRIPTION
+ This function builds a new string from 'str' with all occurances
+ of 'from' replaced by 'to'. Note that the new string will have one
+ extra reference.
+
+KEYWORDS
+ pike_string
--
GitLab