1m_wtransform_layout(3LAYLOaUyTo)ut Service Library Functmi_owntsransform_layout(3LAYOUT)
2
6 m_wtransform_layout - layout transformation for wide character strings
7
9 cc [ flag... ] file... -llayout [ library... ]
10 #include <sys/layout.h>
11 int m_wtransform_layout(LayoutObject layout_object,
15 const wchar_t *InpBuf, const size_t ImpSize, const void *OutBuf,
16 size_t *Outsize, size_t *InpToOut, size_t *OutToInp,
17 unsignedchar *Property, size_t *InpBufIndex);
18
21 The m_wtransform_layout() function performs layout transformations
22 (reordering, shaping, cell determination) or provides additional infor‐
23 mation needed for layout transformation (such as the expected size of
24 the transformed layout, the nesting level of different segments in the
25 text and cross-references between the locations of the corresponding
26 elements before and after the layout transformation). Both the input
27 text and output text are wide character strings.
28 The m_wtransform_layout() function transforms the input text in InpBuf
31 according to the current layout values in layout_object. Any layout
32 value whose value type is LayoutTextDescriptor describes the attributes
33 of the InpBuf and OutBuf arguments. If the attributes are the same for
34 both InpBuf and OutBuf, a null transformation is performed with respect
35 to that specific layout value.
36 The InpBuf argument specifies the source text to be processed. The
39 InpBuf may not be NULL, unless there is a need to reset the internal
40 state.
41 The InpSize argument is the number of bytes within InpBuf to be pro‐
44 cessed by the transformation. Its value will not change after return
45 from the transformation. InpSize set to −1 indicates that the text in
46 InpBuf is delimited by a null code element. If InpSize is not set to
47 −1, it is possible to have some null elements in the input buffer. This
48 might be used, for example, for a "one shot" transformation of several
49 strings, separated by nulls.
50 Output of this function may be one or more of the following depending
53 on the setting of the arguments:
54 OutBuf Any transformed data is stored in OutBuf, converted to
56 ShapeCharset.
57 Outsize The number of wide characters in OutBuf.
60 InpToOut A cross-reference from each InpBuf code element to the
63 transformed data. The cross-reference relates to the data
64 in InpBuf starting with the first element that InpBufIndex
65 points to (and not necessarily starting from the beginning
66 of the InpBuf).
67 OutToInp A cross-reference to each InpBuf code element from the
70 transformed data. The cross-reference relates to the data
71 in InpBuf starting with the first element that InpBufIndex
72 points to (and not necessarily starting from the beginning
73 of the InpBuf).
74 Property A weighted value that represents peculiar input string
77 transformation properties with different connotations as
78 explained below. If this argument is not a nullpointer,
79 it represents an array of values with the same number of
80 elements as the source substring text before the transfor‐
81 mation. Each byte will contain relevant "property" informa‐
82 tion of the corresponding element in InpBuf starting from
83 the element pointed by InpBufIndex. The four rightmost bits
84 of each "property" byte will contain information for bidi‐
85 rectional environments (when ActiveDirectional is True) and
86 they will mean "NestingLevels." The possible value from 0
87 to 15 represents the nesting level of the corresponding
88 element in the InpBuf starting from the element pointed by
89 InpBufIndex. If ActiveDirectional is false the content of
90 NestingLevel bits will be ignored. The leftmost bit of each
91 "property" byte will contain a "new cell indicator" for
92 composed character environments, and will have a value of
93 either 1 (for an element in InpBuf that is transformed to
94 the beginning of a new cell) or 0 (for the "zero-length"
95 composing character elements, when these are grouped into
96 the same presentation cell with a non- composing charac‐
97 ter). Here again, each element of "property" pertains to
98 the elements in the InpBuf starting from the element
99 pointed by InpBufIndex. (Remember that this is not neces‐
100 sarily the beginning of InpBuf). If none of the transforma‐
101 tion properties is required, the argument Property can be
102 NULL. The use of "property" can be enhanced in the future
103 to pertain to other possible usage in other environments.
104 The InpBufIndex argument is an offset value to the location of the
108 transformed text. When m_wtransform_layout() is called, InpBufIndex
109 contains the offset to the element in InpBuf that will be transformed
110 first. (Note that this is not necessarily the first element in InpBuf).
111 At the return from the transformation, InpBufIndex contains the offset
112 to the first element in the InpBuf that has not been transformed. If
113 the entire substring has been transformed successfully, InpBufIndex
114 will be incremented by the amount defined by InpSize.
115 Each of these output arguments may be null to specify that no output is
118 desired for the specific argument, but at least one of them should be
119 set to a non-null value to perform any significant work.
120 In addition to the possible outputs above, layout_object maintains a
123 directional state across calls to the transform functions. The direc‐
124 tional state is reset to its initial state whenever any of the layout
125 values TypeOfText, Orientation, or ImplicitAlg is modified by means of
126 a call to m_setvalues_layout().
127 The layout_object argument specifies a LayoutObject returned by the
130 m_create_layout() function.
131 The OutBufargument contains the transformed data. This argument can be
134 specified as a null pointer to indicate that no transformed data is
135 required.
136 The encoding of the OutBuf argument depends on the ShapeCharset layout
139 value defined in layout_object. If the ActiveShapeEditing layout value
140 is not set (False), the encoding of OutBuf is guaranteed to be the same
141 as the codeset of the locale associated with the LayoutObject defined
142 by layout_object.
143 On input, the OutSize argument specifies the size of the output buffer
146 in number of wide characters. The output buffer should be large enough
147 to contain the transformed result; otherwise, only a partial transfor‐
148 mation is performed. If the ActiveShapeEditing layout value is set
149 (True) the OutBuf should be allocated to contain at least the InpSize
150 multiplied by ShapeCharsetSize.
151 On return, the OutSize argument is modified to the actual number of
154 code elements in OutBuf.
155 When the OutSize argument is specified as zero, the function calculates
158 the size of an output buffer large enough to contain the transformed
159 text, and the result is returned in this field. The content of the buf‐
160 fers specified by InpBuf and OutBuf, and the value of InpBufIndex,
161 remain unchanged. If OutSize = NULL, the EINVAL error condition should
162 be returned.
163 If the InpToOut argument is not a null pointer, it points to an array
166 of values with the same number of wide characters in InpBuf starting
167 with the one pointed by InpBufIndex and up to the end of the substring
168 in the buffer. On output, the nth value in InpToOut corresponds to the
169 nth byte in InpBuf. This value is the index (in units of wide charac‐
170 ters) in OutBufthat identifies the transformed ShapeCharset element of
171 the nth byte in InpBuf.
172 InpToOut may be specified as NULL if no index array from InpBuf to Out‐
175 Buf is desired.
176 If the OutToInp argument is not a null pointer, it points to an array
179 of values with the same number of wide characters as contained in Out‐
180 Buf. On output, the nth value in OutToInp corresponds to the nth byte
181 in OutBuf. This value is the index in InpBuf, starting with wide char‐
182 acter byte pointed to by InpBufIndex, that identifies the logical code
183 element of the nth wide character in OutBuf.
184 OutToInp may be specified as NULL if no index array from OutBuf to
187 InpBuf is desired.
188 To perform shaping of a text string without reordering of code ele‐
191 ments, the layout_object should be set with input and output layout
192 value TypeOfText set to TEXT_VISUAL and both in and out of Orientation
193 set to the same value.
194
196 If successful, the m_wtransform_layout() function returns 0. If unsuc‐
197 cessful, the returned value is −1 and the errno is set to indicate the
198 source of error. When the size of OutBuf is not large enough to contain
199 the entire transformed text, the input text state at the end of the
200 uncompleted transformation is saved internally and the error condition
201 E2BIG is returned in errno.
202
204 The m_wtransform_layout() function may fail if:
205 E2BIG The output buffer is full and the source text is not entirely
207 processed.
208 EBADF The layout values are set to a meaningless combination or the
211 layout object is not valid.
212 EILSEQ Transformation stopped due to an input code element that can‐
215 not be shaped or is invalid. The InpBufIndex argument is set
216 to indicate the code element causing the error. The suspect
217 code element is either a valid code element but cannot be
218 shaped into the ShapeCharset layout value, or is an invalid
219 code element not defined by the codeset of the locale of lay‐
220 out_object. The mbtowc() and wctomb() functions, when used in
221 the same locale as the LayoutObject, can be used to determine
222 if the code element is valid.
223 EINVAL Transformation stopped due to an incomplete composite
226 sequence at the end of the input buffer, or OutSize contains
227 NULL.
228 ERANGE More than 15 embedding levels are in source text or InpBuf
231 contain unbalanced directional layout information (push/pop)
232 or an incomplete composite sequence has been detected in the
233 input buffer at the beginning of the string pointed to by
234 InpBufIndex.
235 An incomplete composite sequence at the end of the input buf‐
237 fer is not always detectable. Sometimes the fact that the
238 sequence is incomplete will only be detected when additional
239 character elements belonging to the composite sequence are
240 found at the beginning of the next input buffer.
241
244 A LayoutObject will have a meaningful combination of default layout
245 values. Whoever chooses to change the default layout values is respon‐
246 sible for making sure that the combination of layout values is meaning‐
247 ful. Otherwise, the result of m_wtransform_layout() might be unpre‐
248 dictable or implementation-specific with errno set to EBADF.
249
251 Example 1 Shaping and reordering input string into output buffer
252 The following example illustrated what the different arguments of
255 m_wtransform_layout() look like when a string in InpBuf is shaped and
256 reordered into OutBuf. Upper-case letters in the example represent
257 left-to-right letters while lower-case letters represent right-to-left
258 letters. xyz represents the shapes of cde.
259 Position: 0123456789
262 InpBuf: AB cde 12z
263 Position: 0123456789
265 OutBuf: AB 12 zyxZ
266 Position: 0123456789
268 OutToInp: 0127865439
269 Position: 0123456789
271 Property.NestLevel: 0001111220
272 Property.CelBdry: 1111111111
273 The values (encoded in bianry) returned in the Property argument define
277 the directionality of each code element in the source text as defined
278 by the type of algorithm used within the layout_object. Whlie the algo‐
279 rithm may be implementation dependent, the resulting values and levels
280 are defined such as to allow a single method to be used in determining
281 the directionality of the sourece text. The base rules are:
282 o Odd levels are always RTL.
285 o Even levels are always LTR.
287 o The Orientation layout value setting determines the initial
289 level (0 or 1) used.
290 Within a Property array each increment in the level indicates the cor‐
293 responding code elements should be presented in the opposite direction.
294 Callers of this function should realize that the Property values for
295 certain code elements is dependent on the context of the given charac‐
296 ter and the layout values: Orientation and ImplicitAlg. Callers should
297 not assume that a given code element always has the same Property value
298 in all cases.
299 Example 2 Algorithm to handle nesting
302 The following is an example of a standard presentation algorithm that
305 handles nesting correctly. The goal of this algorithm is ultimately to
306 return to a zero nest level. Note that more efficient algorithms do
307 exist; the following is provided for clarity rather than for effi‐
308 ciency.
309 1. Search for the highest next level in the string.
312 2. Reverse all surrounding code elements of the same level.
314 Reduce the nest level of these code elements by 1.
315 3. Repeat 1 and 2 until all code elements are of level 0.
317 The following shows the progression of the example from above:
320 Position: 0123456789 0123456789 0123456789
323 InpBuf: AB cde 12Z AB cde 21Z AB 12 edcZ
324 Property.NestLevel: 0001111220 0001111110 0000000000
325 Property.CellBdry: 1111111111 1111111111 1111111111
326
329 See attributes(5) for descriptions of the following attributes:
330 ┌─────────────────────────────┬─────────────────────────────┐
335 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
336 ├─────────────────────────────┼─────────────────────────────┤
337 │Interface Stability │Standard │
338 ├─────────────────────────────┼─────────────────────────────┤
339 │MT-Level │MT-Safe │
340 └─────────────────────────────┴─────────────────────────────┘
341
343 attributes(5), standards(5)
344SunOS 5.11 7 Aug 2006 m_wtransform_layout(3LAYOUT)