1m_transform_layout(3LAYOLUaTy)out Service Library Functimo_ntsransform_layout(3LAYOUT)
2
6 m_transform_layout - layout transformation
7
9 cc [ flag... ] file... -llayout [ library... ]
10 #include <sys/layout.h>
11 int m_transform_layout(LayoutObject layout_object,
15 const char *InpBuf, const size_t ImpSize, const void *OutBuf,
16 size_t *Outsize, size_t *InpToOut, size_t *OutToInp,
17 unsigned char *Property, size_t *InpBufIndex);
18
21 The m_transform_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 character strings.
28 The m_transform_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 bytes 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 null pointer,
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 character).
97 Here again, each element of "property" pertains to the ele‐
98 ments in the InpBuf starting from the element pointed by
99 InpBufIndex. (Remember that this is not necessarily the
100 beginning of InpBuf). If none of the transformation proper‐
101 ties is required, the argument Property can be NULL. The
102 use of "property" can be enhanced in the future to pertain
103 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_transform_layout() is called, InpBufIndex con‐
109 tains 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 The layout object maintains a directional state that keeps track of
123 directional changes, based on the last segment transformed. The direc‐
124 tional state is maintained across calls to the layout transformation
125 functions and allows stream data to be processed with the layout func‐
126 tions. The directional state is reset to its initial state whenever any
127 of the layout values TypeOfText, Orientation, or ImplicitAlg is modi‐
128 fied by means of a call to m_setvalues_layout().
129 The layout_object argument specifies a LayoutObject returned by the
132 m_create_layout() function.
133 The OutBufargument contains the transformed data. This argument can be
136 specified as a null pointer to indicate that no transformed data is
137 required.
138 The encoding of the OutBuf argument depends on the ShapeCharset layout
141 value defined in layout_object. If the ActiveShapeEditing layout value
142 is not set (False), the encoding of OutBuf is guaranteed to be the same
143 as the codeset of the locale associated with the LayoutObject defined
144 by layout_object.
145 On input, the OutSize argument specifies the size of the output buffer
148 in number of bytes. The output buffer should be large enough to contain
149 the transformed result; otherwise, only a partial transformation is
150 performed. If the ActiveShapeEditing layout value is set (True) the
151 OutBuf should be allocated to contain at least the InpSize multiplied
152 by ShapeCharsetSize.
153 On return, the OutSize argument is modified to the actual number of
156 bytes placed in OutBuf.
157 When the OutSize argument is specified as zero, the function calculates
160 the size of an output buffer large enough to contain the transformed
161 text, and the result is returned in this field. The content of the buf‐
162 fers specified by InpBuf and OutBuf, and the value of InpBufIndex,
163 remain unchanged. If OutSize = NULL, the EINVAL error condition should
164 be returned.
165 If the InpToOut argument is not a null pointer, it points to an array
168 of values with the same number of bytes in InpBuf starting with the one
169 pointed by InpBufIndex and up to the end of the substring in the buf‐
170 fer. On output, the nth value in InpToOut corresponds to the nth byte
171 in InpBuf. This value is the index (in units of bytes) in OutBufthat
172 identifies the transformed ShapeCharset element of the nth byte in
173 InpBuf. In the case of multibyte encoding, the index points (for each
174 of the bytes of a code element in the InpBuf) to the first byte of the
175 transformed code element in the OutBuf.
176 InpToOut may be specified as NULL if no index array from InpBuf to Out‐
179 Buf is desired.
180 If the OutToInp argument is not a null pointer, it points to an array
183 of values with the same number of bytes as contained in OutBuf. On out‐
184 put, the nth value in OutToInp corresponds to the nth byte in OutBuf
185 This value is the index in InpBuf, starting with the byte pointed to by
186 InpBufIndex, that identifies the logical code element of the nth byte
187 in OutBuf. In the case of multibyte encoding, the index will point for
188 each of the bytes of a transformed code element in the OutBuf to the
189 first byte of the code element in the InpBuf.
190 OutToInp may be specified as NULL if no index array from OutBuf to
193 InpBuf is desired.
194 To perform shaping of a text string without reordering of code ele‐
197 ments, the layout_object should be set with input and output layout
198 value TypeOfText set to TEXT_VISUAL and both in and out of Orientation
199 set to the same value.
200
202 If successful, the m_transform_layout() function returns 0. If unsuc‐
203 cessful, the returned value is −1 and the errno is set to indicate the
204 source of error. When the size of OutBuf is not large enough to contain
205 the entire transformed text, the input text state at the end of the
206 uncompleted transformation is saved internally and the error condition
207 E2BIG is returned in errno.
208
210 The m_transform_layout() function may fail if:
211 E2BIG The output buffer is full and the source text is not entirely
213 processed.
214 EBADF The layout values are set to a meaningless combination or the
217 layout object is not valid.
218 EILSEQ Transformation stopped due to an input code element that can‐
221 not be shaped or is invalid. The InpBufIndex argument is set
222 to indicate the code element causing the error. The suspect
223 code element is either a valid code element but cannot be
224 shaped into the ShapeCharset layout value, or is an invalid
225 code element not defined by the codeset of the locale of lay‐
226 out_object. The mbtowc() and wctomb() functions, when used in
227 the same locale as the LayoutObject, can be used to determine
228 if the code element is valid.
229 EINVAL Transformation stopped due to an incomplete composite
232 sequence at the end of the input buffer, or OutSize contains
233 NULL.
234 ERANGE More than 15 embedding levels are in source text or InpBuf
237 contain unbalanced directional layout information (push/pop)
238 or an incomplete composite sequence has been detected in the
239 input buffer at the beginning of the string pointed to by
240 InpBufIndex.
241 An incomplete composite sequence at the end of the input buf‐
243 fer is not always detectable. Sometimes, the fact that the
244 sequence is incomplete will only be detected when additional
245 character elements belonging to the composite sequence are
246 found at the beginning of the next input buffer.
247
250 A LayoutObject will have a meaningful combination of default layout
251 values. Whoever chooses to change the default layout values is respon‐
252 sible for making sure that the combination of layout values is meaning‐
253 ful. Otherwise, the result of m_transform_layout() might be unpre‐
254 dictable or implementation-specific with errno set to EBADF.
255
257 See attributes(5) for descriptions of the following attributes:
258 ┌─────────────────────────────┬─────────────────────────────┐
263 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
264 ├─────────────────────────────┼─────────────────────────────┤
265 │Interface Stability │Standard │
266 ├─────────────────────────────┼─────────────────────────────┤
267 │MT-Level │MT-Safe │
268 └─────────────────────────────┴─────────────────────────────┘
269
271 attributes(5), standards(5)
272SunOS 5.11 7 Aug 2006 m_transform_layout(3LAYOUT)