1: <?php
2:
3: /**
4: * This file contains CONTENIDO String API functions.
5: *
6: * If you are planning to add a function, please make sure that:
7: * 1.) The function is in the correct place
8: * 2.) The function is documented
9: * 3.) The function makes sense and is generally usable
10: *
11: * @package Core
12: * @subpackage Backend
13: * @author Timo Hummel
14: * @copyright four for business AG <www.4fb.de>
15: * @license http://www.contenido.org/license/LIZENZ.txt
16: * @link http://www.4fb.de
17: * @link http://www.contenido.org
18: */
19:
20: defined('CON_FRAMEWORK') || die('Illegal call: Missing framework initialization - request aborted.');
21:
22: /**
23: * Trims a string to a given length and makes sure that all words up to $maxlen
24: * are preserved, without exceeding $maxlen.
25: *
26: * Warning: Currently, this function uses a regular ASCII-Whitespace to do the
27: * separation test. If you are using ' ' to create spaces, this function
28: * will fail.
29: *
30: * Example:
31: * $string = "This is a simple test";
32: * echo cApiStrTrimAfterWord($string, 15);
33: *
34: * This would output "This is a", since this function respects word boundaries
35: * and doesn't operate beyond the limit given by $maxlen.
36: *
37: * @deprecated [2015-05-21]
38: * use cString::trimAfterWord
39: *
40: * @param string $string
41: * The string to operate on
42: * @param int $maxlen
43: * The maximum number of characters
44: *
45: * @return string
46: * The resulting string
47: *
48: * @throws cInvalidArgumentException
49: */
50: function cApiStrTrimAfterWord($string, $maxlen) {
51: cDeprecated('This method is deprecated and is not needed any longer');
52: return cString::trimAfterWord($string, $maxlen);
53: }
54:
55: /**
56: * Trims a string to a specific length.
57: * If the string is longer than $maxlen,
58: * dots are inserted ("...") right before $maxlen.
59: *
60: * Example:
61: * $string = "This is a simple test";
62: * echo cApiStrTrimHard ($string, 15);
63: *
64: * This would output "This is a si...", since the string is longer than $maxlen
65: * and the resulting string matches 15 characters including the dots.
66: *
67: * @deprecated [2015-05-21]
68: * use cString::trimHard() instead
69: *
70: * @param string $string
71: * The string to operate on
72: * @param int $maxlen
73: * The maximum number of characters
74: * @param string $fillup [optional]
75: *
76: * @return string
77: * The resulting string
78: *
79: * @throws cInvalidArgumentException
80: */
81: function cApiStrTrimHard($string, $maxlen, $fillup = '...') {
82: cDeprecated('This method is deprecated and is not needed any longer');
83: return cString::trimHard($string, $maxlen, $fillup);
84: }
85:
86: /**
87: * Trims a string to a approximate length.
88: * Sentence boundaries are preserved.
89: *
90: * The algorithm inside calculates the sentence length to the previous and next
91: * sentences. The distance to the next sentence which is smaller will be taken
92: * to
93: * trim the string to match the approximate length parameter.
94: *
95: * Example:
96: *
97: * $string = "This contains two sentences. ";
98: * $string .= "Lets play around with them. ";
99: *
100: * echo cApiStrTrimSentence($string, 40);
101: * echo cApiStrTrimSentence($string, 50);
102: *
103: * The first example would only output the first sentence, the second example
104: * both
105: * sentences.
106: *
107: * Explanation:
108: *
109: * To match the given max length closely, the function calculates the distance
110: * to
111: * the next and previous sentences. Using the maxlength of 40 characters, the
112: * distance to the previous sentence would be 8 characters, and to the next
113: * sentence
114: * it would be 19 characters. Therefore, only the previous sentence is
115: * displayed.
116: *
117: * The second example displays the second sentence also, since the distance to
118: * the
119: * next sentence is only 9 characters, but to the previous it is 18 characters.
120: *
121: * If you specify the boolean flag "$hard", the limit parameter creates a hard
122: * limit
123: * instead of calculating the distance.
124: *
125: * This function ensures that at least one sentence is returned.
126: *
127: * @deprecated [2015-05-21]
128: * use cString::trimSentence
129: *
130: * @param string $string
131: * The string to operate on
132: * @param int $approxlen
133: * The approximate number of characters
134: * @param bool $hard [optional]
135: * If true, use a hard limit for the number of characters
136: *
137: * @return string
138: * The resulting string
139: *
140: * @throws cInvalidArgumentException
141: */
142: function cApiStrTrimSentence($string, $approxlen, $hard = false) {
143: cDeprecated('This method is deprecated and is not needed any longer');
144: return cString::trimSentence($string, $approxlen, $hard);
145: }
146:
147: /**
148: * Converts diactritics to english characters whenever possible.
149: *
150: * For german umlauts, this function converts the umlauts to their ASCII
151: * equivalents (e.g. รค => ae).
152: *
153: * For more information about diacritics, refer to
154: * http://en.wikipedia.org/wiki/Diacritic
155: *
156: * For other languages, the diacritic marks are removed, if possible.
157: *
158: * @deprecated [2015-05-21]
159: * use cString::replaceDiacritics
160: *
161: * @param string $sString
162: * The string to operate on
163: * @param string $sourceEncoding [optional; default: UTF-8]
164: * The source encoding
165: * @param string $targetEncoding [optional; default: UTF-8]
166: * The target encoding
167: *
168: * @return string
169: * The resulting string
170: *
171: * @throws cInvalidArgumentException
172: */
173: function cApiStrReplaceDiacritics($sString, $sourceEncoding = 'UTF-8', $targetEncoding = 'UTF-8') {
174: cDeprecated('This method is deprecated and is not needed any longer');
175: return cString::replaceDiacritics($sString, $sourceEncoding, $targetEncoding);
176: }
177:
178: /**
179: * Converts a string to another encoding.
180: * This function tries to detect which function
181: * to use (either recode or iconv).
182: *
183: * If $sourceEncoding and $targetEncoding are the same, this function returns
184: * immediately.
185: *
186: * For more information about encodings, refer to
187: * http://en.wikipedia.org/wiki/Character_encoding
188: *
189: * For more information about the supported encodings in recode, refer to
190: * http://www.delorie.com/gnu/docs/recode/recode_toc.html
191: *
192: * Note: depending on whether recode or iconv is used, the supported charsets
193: * differ. The following ones are commonly used and are most likely supported by
194: * both converters:
195: *
196: * - ISO-8859-1 to ISO-8859-15
197: * - ASCII
198: * - UTF-8
199: *
200: * @deprecated [2015-05-21]
201: * use cString::recodeString
202: * @todo Check if the charset names are the same for both converters
203: * @todo Implement a converter and charset checker to ensure compilance.
204: *
205: * @param string $sString
206: * The string to operate on
207: * @param string $sourceEncoding
208: * The source encoding (default: ISO-8859-1)
209: * @param string $targetEncoding
210: * The target encoding (if false, use source encoding)
211: *
212: * @return string
213: * The resulting string
214: *
215: * @throws cInvalidArgumentException
216: */
217: function cApiStrRecodeString($sString, $sourceEncoding, $targetEncoding) {
218: cDeprecated('This method is deprecated and is not needed any longer');
219: return cString::recodeString($sString, $sourceEncoding, $targetEncoding);
220: }
221:
222: /**
223: * Removes or converts all "evil" URL characters.
224: * This function removes or converts
225: * all characters which can make an URL invalid.
226: *
227: * Clean characters include:
228: * - All characters between 32 and 126 which are not alphanumeric and
229: * aren't one of the following: _-.
230: *
231: * @deprecated [2015-05-21]
232: * use cString::cleanURLCharacters
233: *
234: * @param string $sString
235: * The string to operate on
236: * @param bool $bReplace [optional]
237: * If true, all "unclean" characters are replaced
238: *
239: * @return string
240: * The resulting string
241: *
242: * @throws cInvalidArgumentException
243: */
244: function cApiStrCleanURLCharacters($sString, $bReplace = false) {
245: cDeprecated('This method is deprecated and is not needed any longer');
246: return cString::cleanURLCharacters($sString, $bReplace);
247: }
248:
249: /**
250: * Normalizes line endings in passed string.
251: *
252: * @deprecated [2015-05-21]
253: * use cString::normalizeLineEndings
254: *
255: * @param string $sString
256: * @param string $sLineEnding
257: * Feasible values are "\n", "\r" or "\r\n"
258: *
259: * @return string
260: *
261: * @throws cInvalidArgumentException
262: */
263: function cApiStrNormalizeLineEndings($sString, $sLineEnding = "\n") {
264: cDeprecated('This method is deprecated and is not needed any longer');
265: return cString::normalizeLineEndings($sString, $sLineEnding);
266: }
267: