1m_wtransform_layout(3LAYLOaUyTo)ut Service Library Functmi_owntsransform_layout(3LAYOUT)
2
3
4

NAME

6       m_wtransform_layout - layout transformation for wide character strings
7

SYNOPSIS

9       cc [ flag... ] file... -llayout [ library... ]
10       #include <sys/layout.h>
11
12
13
14       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
19

DESCRIPTION

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
29
30       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
37
38       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
42
43       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
51
52       Output of this function may be one or more of the  following  depending
53       on the setting of the arguments:
54
55       OutBuf      Any  transformed  data  is  stored  in OutBuf, converted to
56                   ShapeCharset.
57
58
59       Outsize     The number of wide characters in OutBuf.
60
61
62       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
68
69       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
75
76       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
105
106
107       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
116
117       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
121
122       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
128
129       The layout_object argument specifies a  LayoutObject  returned  by  the
130       m_create_layout() function.
131
132
133       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
137
138       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
144
145       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
152
153       On return, the OutSize argument is modified to  the  actual  number  of
154       code elements in OutBuf.
155
156
157       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
164
165       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
173
174       InpToOut may be specified as NULL if no index array from InpBuf to Out‐
175       Buf is desired.
176
177
178       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
185
186       OutToInp may be specified as NULL if no  index  array  from  OutBuf  to
187       InpBuf is desired.
188
189
190       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

RETURN VALUES

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

ERRORS

204       The m_wtransform_layout() function may fail if:
205
206       E2BIG     The output buffer is full and the source text is not entirely
207                 processed.
208
209
210       EBADF     The layout values are set to a meaningless combination or the
211                 layout object is not valid.
212
213
214       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
224
225       EINVAL    Transformation   stopped   due  to  an  incomplete  composite
226                 sequence at the end of the input buffer, or OutSize  contains
227                 NULL.
228
229
230       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
236                 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
242

USAGE

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

EXAMPLES

251       Example 1 Shaping and reordering input string into output buffer
252
253
254       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
260
261         Position:                    0123456789
262         InpBuf:                      AB cde 12z
263
264         Position:                    0123456789
265         OutBuf:                      AB 12 zyxZ
266
267         Position:                    0123456789
268         OutToInp:                    0127865439
269
270         Position:                    0123456789
271         Property.NestLevel:          0001111220
272         Property.CelBdry:            1111111111
273
274
275
276       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
283
284           o      Odd levels are always RTL.
285
286           o      Even levels are always LTR.
287
288           o      The Orientation layout value setting determines the  initial
289                  level (0 or 1) used.
290
291
292       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
300
301       Example 2 Algorithm to handle nesting
302
303
304       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
310
311           1.     Search for the highest next level in the string.
312
313           2.     Reverse  all  surrounding  code  elements of the same level.
314                  Reduce the nest level of these code elements by 1.
315
316           3.     Repeat 1 and 2 until all code elements are of level 0.
317
318
319       The following shows the progression of the example from above:
320
321
322         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
327

ATTRIBUTES

329       See attributes(5) for descriptions of the following attributes:
330
331
332
333
334       ┌─────────────────────────────┬─────────────────────────────┐
335       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
336       ├─────────────────────────────┼─────────────────────────────┤
337       │Interface Stability          │Standard                     │
338       ├─────────────────────────────┼─────────────────────────────┤
339       │MT-Level                     │MT-Safe                      │
340       └─────────────────────────────┴─────────────────────────────┘
341

SEE ALSO

343       attributes(5), standards(5)
344
345
346
347SunOS 5.11                        7 Aug 2006      m_wtransform_layout(3LAYOUT)
Impressum