Commit | Line | Data |
---|---|---|
0f2d19dd JB |
1 | /* classes: h_files */ |
2 | ||
36284627 DH |
3 | #ifndef SCM_STRINGS_H |
4 | #define SCM_STRINGS_H | |
8c494e99 | 5 | |
35920c00 | 6 | /* Copyright (C) 1995,1996,1997,1998,2000,2001, 2004, 2005, 2006, 2008, 2009 Free Software Foundation, Inc. |
8c494e99 | 7 | * |
73be1d9e MV |
8 | * This library is free software; you can redistribute it and/or |
9 | * modify it under the terms of the GNU Lesser General Public | |
10 | * License as published by the Free Software Foundation; either | |
11 | * version 2.1 of the License, or (at your option) any later version. | |
8c494e99 | 12 | * |
73be1d9e | 13 | * This library is distributed in the hope that it will be useful, |
0f2d19dd | 14 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
73be1d9e MV |
15 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
16 | * Lesser General Public License for more details. | |
8c494e99 | 17 | * |
73be1d9e MV |
18 | * You should have received a copy of the GNU Lesser General Public |
19 | * License along with this library; if not, write to the Free Software | |
92205699 | 20 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA |
73be1d9e | 21 | */ |
d3a6bc94 | 22 | |
0f2d19dd JB |
23 | \f |
24 | ||
b4309c3c | 25 | #include "libguile/__scm.h" |
0f2d19dd JB |
26 | |
27 | \f | |
28 | ||
3ee86942 | 29 | /* String representation. |
c829a427 | 30 | |
3ee86942 MV |
31 | A string is a piece of a stringbuf. A stringbuf can be used by |
32 | more than one string. When a string is written to and the | |
33 | stringbuf of that string is used by more than one string, a new | |
34 | stringbuf is created. That is, strings are copy-on-write. This | |
35 | behavior can be used to make the substring operation quite | |
36 | efficient. | |
c829a427 | 37 | |
3ee86942 MV |
38 | The implementation is tuned so that mutating a string is costly, |
39 | but just reading it is cheap and lock-free. | |
0f2d19dd | 40 | |
3ee86942 MV |
41 | There are also mutation-sharing strings. They refer to a part of |
42 | an ordinary string. Writing to a mutation-sharing string just | |
43 | writes to the ordinary string. | |
44 | ||
45 | ||
46 | Internal, low level interface to the character arrays | |
47 | ||
48 | - Use scm_i_string_chars to get a pointer to the byte array of a | |
49 | string for reading. Use scm_i_string_length to get the number of | |
50 | bytes in that array. The array is not null-terminated. | |
51 | ||
52 | - The array is valid as long as the corresponding SCM object is | |
53 | protected but only until the next SCM_TICK. During such a 'safe | |
54 | point', strings might change their representation. | |
55 | ||
56 | - Use scm_i_string_writable_chars to get the same pointer as with | |
57 | scm_i_string_chars, but for reading and writing. This is a | |
58 | potentially costly operation since it implements the | |
59 | copy-on-write behavior. When done with the writing, call | |
60 | scm_i_string_stop_writing. You must do this before the next | |
61 | SCM_TICK. (This means, before calling almost any other scm_ | |
62 | function and you can't allow throws, of course.) | |
63 | ||
64 | - New strings can be created with scm_i_make_string. This gives | |
65 | access to a writable pointer that remains valid as long as nobody | |
66 | else makes a copy-on-write substring of the string. Do not call | |
67 | scm_i_string_stop_writing for this pointer. | |
68 | ||
69 | Legacy interface | |
70 | ||
274acbda | 71 | - SCM_STRINGP is just scm_is_string. |
3ee86942 MV |
72 | |
73 | - SCM_STRING_CHARS uses scm_i_string_writable_chars and immediately | |
74 | calls scm_i_stop_writing, hoping for the best. SCM_STRING_LENGTH | |
274acbda MV |
75 | is the same as scm_i_string_length. SCM_STRING_CHARS will throw |
76 | an error for for strings that are not null-terminated. | |
3ee86942 | 77 | */ |
0f2d19dd | 78 | |
33b001fd MV |
79 | SCM_API SCM scm_string_p (SCM x); |
80 | SCM_API SCM scm_string (SCM chrs); | |
c829a427 MV |
81 | SCM_API SCM scm_make_string (SCM k, SCM chr); |
82 | SCM_API SCM scm_string_length (SCM str); | |
83 | SCM_API SCM scm_string_ref (SCM str, SCM k); | |
84 | SCM_API SCM scm_string_set_x (SCM str, SCM k, SCM chr); | |
85 | SCM_API SCM scm_substring (SCM str, SCM start, SCM end); | |
ed35de72 | 86 | SCM_API SCM scm_substring_read_only (SCM str, SCM start, SCM end); |
3ee86942 MV |
87 | SCM_API SCM scm_substring_shared (SCM str, SCM start, SCM end); |
88 | SCM_API SCM scm_substring_copy (SCM str, SCM start, SCM end); | |
c829a427 MV |
89 | SCM_API SCM scm_string_append (SCM args); |
90 | ||
3ee86942 MV |
91 | SCM_API SCM scm_c_make_string (size_t len, SCM chr); |
92 | SCM_API size_t scm_c_string_length (SCM str); | |
071bb6a8 | 93 | SCM_API size_t scm_c_symbol_length (SCM sym); |
3ee86942 MV |
94 | SCM_API SCM scm_c_string_ref (SCM str, size_t pos); |
95 | SCM_API void scm_c_string_set_x (SCM str, size_t pos, SCM chr); | |
96 | SCM_API SCM scm_c_substring (SCM str, size_t start, size_t end); | |
ed35de72 | 97 | SCM_API SCM scm_c_substring_read_only (SCM str, size_t start, size_t end); |
3ee86942 MV |
98 | SCM_API SCM scm_c_substring_shared (SCM str, size_t start, size_t end); |
99 | SCM_API SCM scm_c_substring_copy (SCM str, size_t start, size_t end); | |
0f2d19dd | 100 | |
c829a427 MV |
101 | SCM_API int scm_is_string (SCM x); |
102 | SCM_API SCM scm_from_locale_string (const char *str); | |
103 | SCM_API SCM scm_from_locale_stringn (const char *str, size_t len); | |
104 | SCM_API SCM scm_take_locale_string (char *str); | |
105 | SCM_API SCM scm_take_locale_stringn (char *str, size_t len); | |
106 | SCM_API char *scm_to_locale_string (SCM str); | |
107 | SCM_API char *scm_to_locale_stringn (SCM str, size_t *lenp); | |
108 | SCM_API size_t scm_to_locale_stringbuf (SCM str, char *buf, size_t max_len); | |
6ba93e5e | 109 | |
3ee86942 MV |
110 | SCM_API SCM scm_makfromstrs (int argc, char **argv); |
111 | ||
35920c00 LC |
112 | \f |
113 | /* internal constants */ | |
114 | ||
115 | /* Type tag for read-only strings. */ | |
116 | #define scm_tc7_ro_string (scm_tc7_string + 0x200) | |
117 | ||
118 | /* Flags for shared and inline strings. */ | |
119 | #define SCM_I_STRINGBUF_F_SHARED 0x100 | |
120 | #define SCM_I_STRINGBUF_F_INLINE 0x200 | |
121 | ||
122 | ||
3ee86942 MV |
123 | /* internal accessor functions. Arguments must be valid. */ |
124 | ||
102dbb6f LC |
125 | SCM_INTERNAL SCM scm_i_make_string (size_t len, char **datap); |
126 | SCM_INTERNAL SCM scm_i_substring (SCM str, size_t start, size_t end); | |
127 | SCM_INTERNAL SCM scm_i_substring_read_only (SCM str, size_t start, size_t end); | |
128 | SCM_INTERNAL SCM scm_i_substring_shared (SCM str, size_t start, size_t end); | |
129 | SCM_INTERNAL SCM scm_i_substring_copy (SCM str, size_t start, size_t end); | |
130 | SCM_INTERNAL size_t scm_i_string_length (SCM str); | |
131 | SCM_API /* FIXME: not internal */ const char *scm_i_string_chars (SCM str); | |
132 | SCM_API /* FIXME: not internal */ char *scm_i_string_writable_chars (SCM str); | |
133 | SCM_INTERNAL void scm_i_string_stop_writing (void); | |
3ee86942 MV |
134 | |
135 | /* internal functions related to symbols. */ | |
136 | ||
102dbb6f LC |
137 | SCM_INTERNAL SCM scm_i_make_symbol (SCM name, scm_t_bits flags, |
138 | unsigned long hash, SCM props); | |
139 | SCM_INTERNAL SCM | |
fd0a5bbc HWN |
140 | scm_i_c_make_symbol (const char *name, size_t len, |
141 | scm_t_bits flags, unsigned long hash, SCM props); | |
102dbb6f | 142 | SCM_INTERNAL SCM |
fd0a5bbc HWN |
143 | scm_i_c_take_symbol (char *name, size_t len, |
144 | scm_t_bits flags, unsigned long hash, SCM props); | |
102dbb6f LC |
145 | SCM_INTERNAL const char *scm_i_symbol_chars (SCM sym); |
146 | SCM_INTERNAL size_t scm_i_symbol_length (SCM sym); | |
147 | SCM_INTERNAL SCM scm_i_symbol_substring (SCM sym, size_t start, size_t end); | |
3ee86942 | 148 | |
c829a427 | 149 | /* internal utility functions. */ |
6ba93e5e | 150 | |
102dbb6f | 151 | SCM_INTERNAL char **scm_i_allocate_string_pointers (SCM list); |
102dbb6f LC |
152 | SCM_INTERNAL void scm_i_get_substring_spec (size_t len, |
153 | SCM start, size_t *cstart, | |
154 | SCM end, size_t *cend); | |
155 | SCM_INTERNAL SCM scm_i_take_stringbufn (char *str, size_t len); | |
6ba93e5e | 156 | |
3ee86942 MV |
157 | /* deprecated stuff */ |
158 | ||
159 | #if SCM_ENABLE_DEPRECATED | |
160 | ||
fe78c51a MV |
161 | SCM_API int scm_i_deprecated_stringp (SCM obj); |
162 | SCM_API char *scm_i_deprecated_string_chars (SCM str); | |
163 | SCM_API size_t scm_i_deprecated_string_length (SCM str); | |
164 | ||
165 | #define SCM_STRINGP(x) scm_i_deprecated_stringp(x) | |
166 | #define SCM_STRING_CHARS(x) scm_i_deprecated_string_chars(x) | |
167 | #define SCM_STRING_LENGTH(x) scm_i_deprecated_string_length(x) | |
e654b062 | 168 | #define SCM_STRING_UCHARS(str) ((unsigned char *)SCM_STRING_CHARS (str)) |
3ee86942 MV |
169 | |
170 | #endif | |
171 | ||
102dbb6f | 172 | SCM_INTERNAL void scm_init_strings (void); |
6ba93e5e | 173 | |
36284627 | 174 | #endif /* SCM_STRINGS_H */ |
89e00824 ML |
175 | |
176 | /* | |
177 | Local Variables: | |
178 | c-file-style: "gnu" | |
179 | End: | |
180 | */ |