xquery_functions.h
Go to the documentation of this file.
1 /*
2  * Copyright 2006-2008 The FLWOR Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef ZORBA_XQUERY_FUNCTIONS_API_H
18 #define ZORBA_XQUERY_FUNCTIONS_API_H
19 
20 #include <zorba/config.h>
22 #include <zorba/zorba_string.h>
23 
24 namespace zorba {
25 
26 ///////////////////////////////////////////////////////////////////////////////
27 
28 /**
29  * Provides a way for a function to return a sequence of some type \c T that
30  * can be iterated over.
31  *
32  * @tparam T The type of sequence.
33  */
34 template<typename T>
35 class Sequence {
36 public:
37  typedef T value_type;
38 
39  struct iterator {
40  virtual ~iterator() { }
41  virtual bool next( value_type *result ) = 0;
42  };
43 
44  /**
45  * Constructs a new %Sequence.
46  * This constructor is intended only for function implementors.
47  *
48  * @param i The iterator that provides the elements of the sequence.
49  * Ownership of the iterator is taken.
50  */
51  Sequence( iterator *i ) : i_( i ) { }
52 
53  /**
54  * Copy constructs a %Sequence.
55  *
56  * @param s The %Sequence to copy from. Note that it is a destructive copy
57  * in that the sequence of \a s is 'i' moved.
58  */
59  Sequence( Sequence const &s ) : i_( std::move( s.i_ ) ) { }
60 
61  /**
62  * Gets the next element in the sequence.
63  *
64  * @param result A pointer to the variable to receive the next element.
65  * @return \c true only if there is a next element.
66  */
67  bool next( value_type *result ) {
68  return i_->next( result );
69  }
70 
71 private:
72  mutable std::unique_ptr<iterator> i_;
73 
74  // forbid
75  Sequence& operator=( Sequence const& );
76 };
77 
78 ///////////////////////////////////////////////////////////////////////////////
79 
80 namespace fn {
81 
82 ////////// 5.4 Functions on string values /////////////////////////////////////
83 
84 /**
85  * Translates every character to its upper-case correspondent as defined in the
86  * appropriate case mappings section in the Unicode standard.
87  *
88  * Every lower-case character that does not have an upper-case correspondent,
89  * as well as every upper-case character, is included in the returned value in
90  * its original form.
91  *
92  * @param arg The string to translate.
93  * @return \a arg translated to upper-case.
94  */
95 ZORBA_DLL_PUBLIC
96 String upper_case( String const &arg );
97 
98 /**
99  * Translates every character to its lower-case correspondent as defined in the
100  * appropriate case mappings section in the Unicode standard.
101  *
102  * Every upper-case character that does not have a lower-case correspondent, as
103  * well as every lower-case character, is included in the returned value in its
104  * original form.
105  *
106  * @param arg The string to translate.
107  * @return \a arg translated to lower-case.
108  */
109 ZORBA_DLL_PUBLIC
110 String lower_case( String const &arg );
111 
112 ////////// 5.5 Functions based on substring matching //////////////////////////
113 
114 /**
115  * Tests whether or not the value of \a arg1 ends with a sequence of
116  * collation units that provides a match to the collation units of \a arg2.
117  *
118  * @param arg1 The string to test.
119  * @param arg2 The substring.
120  * @return \c true only if \a arg1 ends with \a arg2 or \a arg2 is the
121  * zero-length string.
122  */
123 ZORBA_DLL_PUBLIC
124 bool ends_with( String const &arg1, String const &arg2 );
125 
126 /**
127  * Tests whether or not the value of \a arg1 ends with a sequence of
128  * collation units that provides a match to the collation units of \a arg2.
129  *
130  * @param arg1 The string to test.
131  * @param arg2 The substring.
132  * @return \c true only if \a arg1 ends with \a arg2 or \a arg2 is the
133  * zero-length string.
134  */
135 ZORBA_DLL_PUBLIC
136 bool ends_with( String const &arg1, char const *arg2 );
137 
138 /**
139  * Tests whether or not the value of \a arg1 starts with a sequence of
140  * collation units that provides a match to the collation units of \a arg2.
141  *
142  * @param arg1 The string to test.
143  * @param arg2 The substring.
144  * @return \c true only if \a arg1 starts with \a arg2 or \a arg2 is the
145  * zero-length string.
146  */
147 ZORBA_DLL_PUBLIC
148 bool starts_with( String const &arg1, String const &arg2 );
149 
150 /**
151  * Tests whether or not the value of \a arg1 starts with a sequence of
152  * collation units that provides a match to the collation units of \a arg2.
153  *
154  * @param arg1 The string to test.
155  * @param arg2 The substring.
156  * @return \c true only if \a arg1 starts with \a arg2 or \a arg2 is the
157  * zero-length string.
158  */
159 ZORBA_DLL_PUBLIC
160 bool starts_with( String const &arg1, char const *arg2 );
161 
162 //////// 6 Functions that manipulate URIs /////////////////////////////////////
163 
164 /**
165  * Encodes reserved characters in an xs:string that is intended to be used in
166  * the path segment of a URI. It is invertible but not idempotent.
167  *
168  * This function applies the URI escaping rules defined in section 2 of [RFC
169  * 3986] to the xs:string supplied as \a uri_part. The effect of the function
170  * is to escape reserved characters. Each such character in the string is
171  * replaced with its percent-encoded form as described in [RFC 3986].
172  *
173  * All characters are escaped except those identified as "unreserved" by [RFC
174  * 3986], that is the upper- and lower-case letters A-Z, the digits 0-9,
175  * HYPHEN-MINUS ("-"), LOW LINE ("_"), FULL STOP ".", and TILDE "~".
176  *
177  * @param uri_part The URI to be encoded.
178  * @return the encoded string.
179  */
180 ZORBA_DLL_PUBLIC
181 String encode_for_uri( String const &uri_part );
182 
183 ////////// 7.6 String Functions that Use Pattern Matching /////////////////////
184 
185 /**
186  * This function breaks the \a input string into a sequence of strings,
187  * treating any substring that matches \a pattern as a separator. The
188  * separators themselves are not returned.
189  *
190  * Performance note: if \a pattern is a simple string (not a regular expression
191  * with meta-characers), it is more efficient to use String::find().
192  *
193  * @param input The string to be split into tokens. If \a input is the empty
194  * sequence, or if \a input is the zero-length string, the result is the empty
195  * sequence.
196  * @param pattern The regular expression. If it matches a zero-length string,
197  * then an error is raised: [err:FORX0003].
198  * @param flags The regular expression flags, if any.
199  * @return a sequence of strings for the tokens.
200  */
201 ZORBA_DLL_PUBLIC
202 Sequence<String> tokenize( String const &input, char const *pattern,
203  char const *flags = "" );
204 
205 /**
206  * This function breaks the \a input string into a sequence of strings,
207  * treating any substring that matches \a pattern as a separator. The
208  * separators themselves are not returned.
209  *
210  * Performance note: if \a pattern is a simple string (not a regular expression
211  * with meta-characers), it is more efficient to use String::find().
212  *
213  * @param input The string to be split into tokens. If \a input is the empty
214  * sequence, or if \a input is the zero-length string, the result is the empty
215  * sequence.
216  * @param pattern The regular expression. If it matches a zero-length string,
217  * then an error is raised: [err:FORX0003].
218  * @param flags The regular expression flags, if any.
219  * @return a sequence of strings for the tokens.
220  */
221 inline
222 Sequence<String> tokenize( String const &input, String const &pattern,
223  char const *flags = "" ) {
224  return tokenize( input, pattern.c_str(), flags );
225 }
226 
227 ///////////////////////////////////////////////////////////////////////////////
228 
229 } // namespace fn
230 } // namespace zorba
231 
232 #endif /* ZORBA_XQUERY_FUNCTIONS_API_H */
233 /* vim:set et sw=2 ts=2: */