Ruby: include/ruby/internal/encoding/transcode.h Source File

Ruby 3.4.3p32 (2025-04-14 revision d0b7e5b6a04bde21ca483d20a1546b28b401c2d4)

transcode.h
Go to the documentation of this file.
1#ifndef RUBY_INTERNAL_ENCODING_TRANSCODE_H /*-*-C++-*-vi:se ft=cpp:*/
2#define RUBY_INTERNAL_ENCODING_TRANSCODE_H
23
24#include "ruby/internal/dllexport.h"
25#include "ruby/internal/value.h"
26
27 RBIMPL_SYMBOL_EXPORT_BEGIN()
28
29
30typedef enum {
31
35 econv_invalid_byte_sequence,
36
41 econv_undefined_conversion,
42
46 econv_destination_buffer_full,
47
51 econv_source_buffer_empty,
52
57 econv_finished,
58
63 econv_after_output,
64
69 econv_incomplete_input
70} rb_econv_result_t;
71
73 typedef struct rb_econv_t rb_econv_t;
74
95 VALUE rb_str_encode(VALUE str, VALUE to, int ecflags, VALUE ecopts);
96
121int rb_econv_has_convpath_p(const char* from_encoding, const char* to_encoding);
122
136int rb_econv_prepare_options(VALUE opthash, VALUE *ecopts, int ecflags);
137
150int rb_econv_prepare_opts(VALUE opthash, VALUE *ecopts);
151
163 rb_econv_t *rb_econv_open(const char *source_encoding, const char *destination_encoding, int ecflags);
164
179 rb_econv_t *rb_econv_open_opts(const char *source_encoding, const char *destination_encoding, int ecflags, VALUE ecopts);
180
197 rb_econv_result_t rb_econv_convert(rb_econv_t *ec,
198 const unsigned char **source_buffer_ptr, const unsigned char *source_buffer_end,
199 unsigned char **destination_buffer_ptr, unsigned char *destination_buffer_end,
200 int flags);
201
209void rb_econv_close(rb_econv_t *ec);
210
224int rb_econv_set_replacement(rb_econv_t *ec, const unsigned char *str, size_t len, const char *encname);
225
244int rb_econv_decorate_at_first(rb_econv_t *ec, const char *decorator_name);
245
257int rb_econv_decorate_at_last(rb_econv_t *ec, const char *decorator_name);
258
268 VALUE rb_econv_open_exc(const char *senc, const char *denc, int ecflags);
269
285int rb_econv_insert_output(rb_econv_t *ec,
286 const unsigned char *str, size_t len, const char *str_encoding);
287
296const char *rb_econv_encoding_to_insert_output(rb_econv_t *ec);
297
306void rb_econv_check_error(rb_econv_t *ec);
307
318 VALUE rb_econv_make_exception(rb_econv_t *ec);
319
327int rb_econv_putbackable(rb_econv_t *ec);
328
339void rb_econv_putback(rb_econv_t *ec, unsigned char *p, int n);
340
352const char *rb_econv_asciicompat_encoding(const char *encname);
353
366 VALUE rb_econv_str_convert(rb_econv_t *ec, VALUE src, int flags);
367
383 VALUE rb_econv_substr_convert(rb_econv_t *ec, VALUE src, long byteoff, long bytesize, int flags);
384
400 VALUE rb_econv_str_append(rb_econv_t *ec, VALUE src, VALUE dst, int flags);
401
419 VALUE rb_econv_substr_append(rb_econv_t *ec, VALUE src, long byteoff, long bytesize, VALUE dst, int flags);
420
436 VALUE rb_econv_append(rb_econv_t *ec, const char *bytesrc, long bytesize, VALUE dst, int flags);
437
447void rb_econv_binmode(rb_econv_t *ec);
448
452 enum ruby_econv_flag_type {
453
459
461 RUBY_ECONV_ERROR_HANDLER_MASK = 0x000000ff,
462
464 RUBY_ECONV_INVALID_MASK = 0x0000000f,
465
467 RUBY_ECONV_INVALID_REPLACE = 0x00000002,
468
470 RUBY_ECONV_UNDEF_MASK = 0x000000f0,
471
473 RUBY_ECONV_UNDEF_REPLACE = 0x00000020,
474
476 RUBY_ECONV_UNDEF_HEX_CHARREF = 0x00000030,
477
479 RUBY_ECONV_DECORATOR_MASK = 0x0001ff00,
480
482 RUBY_ECONV_NEWLINE_DECORATOR_MASK = 0x00007f00,
483
485 RUBY_ECONV_NEWLINE_DECORATOR_READ_MASK = 0x00000f00,
486
488 RUBY_ECONV_NEWLINE_DECORATOR_WRITE_MASK = 0x00007000,
489
491 RUBY_ECONV_UNIVERSAL_NEWLINE_DECORATOR = 0x00000100,
492
494 RUBY_ECONV_CRLF_NEWLINE_DECORATOR = 0x00001000,
495
497 RUBY_ECONV_CR_NEWLINE_DECORATOR = 0x00002000,
498
500 RUBY_ECONV_LF_NEWLINE_DECORATOR = 0x00004000,
501
503 RUBY_ECONV_XML_TEXT_DECORATOR = 0x00008000,
504
506 RUBY_ECONV_XML_ATTR_CONTENT_DECORATOR = 0x00010000,
507
509 RUBY_ECONV_STATEFUL_DECORATOR_MASK = 0x00f00000,
510
512 RUBY_ECONV_XML_ATTR_QUOTE_DECORATOR = 0x00100000,
513
515 RUBY_ECONV_DEFAULT_NEWLINE_DECORATOR =
516#if defined(RUBY_TEST_CRLF_ENVIRONMENT) || defined(_WIN32)
517 RUBY_ECONV_CRLF_NEWLINE_DECORATOR,
518#else
519 0,
520#endif
521
522#define ECONV_ERROR_HANDLER_MASK RUBY_ECONV_ERROR_HANDLER_MASK
523#define ECONV_INVALID_MASK RUBY_ECONV_INVALID_MASK
524#define ECONV_INVALID_REPLACE RUBY_ECONV_INVALID_REPLACE
525#define ECONV_UNDEF_MASK RUBY_ECONV_UNDEF_MASK
526#define ECONV_UNDEF_REPLACE RUBY_ECONV_UNDEF_REPLACE
527#define ECONV_UNDEF_HEX_CHARREF RUBY_ECONV_UNDEF_HEX_CHARREF
528#define ECONV_DECORATOR_MASK RUBY_ECONV_DECORATOR_MASK
529#define ECONV_NEWLINE_DECORATOR_MASK RUBY_ECONV_NEWLINE_DECORATOR_MASK
530#define ECONV_NEWLINE_DECORATOR_READ_MASK RUBY_ECONV_NEWLINE_DECORATOR_READ_MASK
531#define ECONV_NEWLINE_DECORATOR_WRITE_MASK RUBY_ECONV_NEWLINE_DECORATOR_WRITE_MASK
532#define ECONV_UNIVERSAL_NEWLINE_DECORATOR RUBY_ECONV_UNIVERSAL_NEWLINE_DECORATOR
533#define ECONV_CRLF_NEWLINE_DECORATOR RUBY_ECONV_CRLF_NEWLINE_DECORATOR
534#define ECONV_CR_NEWLINE_DECORATOR RUBY_ECONV_CR_NEWLINE_DECORATOR
535#define ECONV_LF_NEWLINE_DECORATOR RUBY_ECONV_LF_NEWLINE_DECORATOR
536#define ECONV_XML_TEXT_DECORATOR RUBY_ECONV_XML_TEXT_DECORATOR
537#define ECONV_XML_ATTR_CONTENT_DECORATOR RUBY_ECONV_XML_ATTR_CONTENT_DECORATOR
538#define ECONV_STATEFUL_DECORATOR_MASK RUBY_ECONV_STATEFUL_DECORATOR_MASK
539#define ECONV_XML_ATTR_QUOTE_DECORATOR RUBY_ECONV_XML_ATTR_QUOTE_DECORATOR
540#define ECONV_DEFAULT_NEWLINE_DECORATOR RUBY_ECONV_DEFAULT_NEWLINE_DECORATOR
542
548
550 RUBY_ECONV_PARTIAL_INPUT = 0x00020000,
551
553 RUBY_ECONV_AFTER_OUTPUT = 0x00040000,
554#define ECONV_PARTIAL_INPUT RUBY_ECONV_PARTIAL_INPUT
555#define ECONV_AFTER_OUTPUT RUBY_ECONV_AFTER_OUTPUT
556
557 RUBY_ECONV_FLAGS_PLACEHOLDER
558};
559
560 RBIMPL_SYMBOL_EXPORT_END()
561
562#endif /* RUBY_INTERNAL_ENCODING_TRANSCODE_H */
dllexport.h
Tweaking visibility of C variables/functions.
RBIMPL_SYMBOL_EXPORT_END
#define RBIMPL_SYMBOL_EXPORT_END()
Counterpart of RBIMPL_SYMBOL_EXPORT_BEGIN.
Definition dllexport.h:74
RBIMPL_SYMBOL_EXPORT_BEGIN
#define RBIMPL_SYMBOL_EXPORT_BEGIN()
Shortcut macro equivalent to RUBY_SYMBOL_EXPORT_BEGIN extern "C" {.
Definition dllexport.h:65
RUBY_ECONV_STATEFUL_DECORATOR_MASK
@ RUBY_ECONV_STATEFUL_DECORATOR_MASK
(Unclear; seems unused).
Definition transcode.h:509
RUBY_ECONV_CRLF_NEWLINE_DECORATOR
@ RUBY_ECONV_CRLF_NEWLINE_DECORATOR
CR to CRLF conversion shall happen.
Definition transcode.h:494
RUBY_ECONV_AFTER_OUTPUT
@ RUBY_ECONV_AFTER_OUTPUT
Instructs the converter to stop after output.
Definition transcode.h:553
RUBY_ECONV_FLAGS_PLACEHOLDER
@ RUBY_ECONV_FLAGS_PLACEHOLDER
Placeholder (not used)
Definition transcode.h:557
RUBY_ECONV_NEWLINE_DECORATOR_WRITE_MASK
@ RUBY_ECONV_NEWLINE_DECORATOR_WRITE_MASK
(Unclear; seems unused).
Definition transcode.h:488
RUBY_ECONV_LF_NEWLINE_DECORATOR
@ RUBY_ECONV_LF_NEWLINE_DECORATOR
CRLF to LF conversion shall happen.
Definition transcode.h:500
RUBY_ECONV_ERROR_HANDLER_MASK
@ RUBY_ECONV_ERROR_HANDLER_MASK
Mask for error handling related bits.
Definition transcode.h:461
RUBY_ECONV_UNDEF_MASK
@ RUBY_ECONV_UNDEF_MASK
Special handling of undefined conversion are there.
Definition transcode.h:470
RUBY_ECONV_XML_ATTR_CONTENT_DECORATOR
@ RUBY_ECONV_XML_ATTR_CONTENT_DECORATOR
Texts shall be AttrValue escaped.
Definition transcode.h:506
RUBY_ECONV_INVALID_REPLACE
@ RUBY_ECONV_INVALID_REPLACE
Invalid sequences shall be replaced.
Definition transcode.h:467
RUBY_ECONV_XML_TEXT_DECORATOR
@ RUBY_ECONV_XML_TEXT_DECORATOR
Texts shall be XML-escaped.
Definition transcode.h:503
RUBY_ECONV_NEWLINE_DECORATOR_MASK
@ RUBY_ECONV_NEWLINE_DECORATOR_MASK
Newline converters are there.
Definition transcode.h:482
RUBY_ECONV_UNDEF_HEX_CHARREF
@ RUBY_ECONV_UNDEF_HEX_CHARREF
Undefined characters shall be escaped.
Definition transcode.h:476
RUBY_ECONV_PARTIAL_INPUT
@ RUBY_ECONV_PARTIAL_INPUT
Indicates the input is a part of much larger one.
Definition transcode.h:550
RUBY_ECONV_UNIVERSAL_NEWLINE_DECORATOR
@ RUBY_ECONV_UNIVERSAL_NEWLINE_DECORATOR
Universal newline mode.
Definition transcode.h:491
RUBY_ECONV_INVALID_MASK
@ RUBY_ECONV_INVALID_MASK
Special handling of invalid sequences are there.
Definition transcode.h:464
RUBY_ECONV_UNDEF_REPLACE
@ RUBY_ECONV_UNDEF_REPLACE
Undefined characters shall be replaced.
Definition transcode.h:473
RUBY_ECONV_DECORATOR_MASK
@ RUBY_ECONV_DECORATOR_MASK
Decorators are there.
Definition transcode.h:479
RUBY_ECONV_XML_ATTR_QUOTE_DECORATOR
@ RUBY_ECONV_XML_ATTR_QUOTE_DECORATOR
Texts shall be AttrValue escaped.
Definition transcode.h:512
RUBY_ECONV_DEFAULT_NEWLINE_DECORATOR
@ RUBY_ECONV_DEFAULT_NEWLINE_DECORATOR
Newline decorator's default.
Definition transcode.h:515
RUBY_ECONV_NEWLINE_DECORATOR_READ_MASK
@ RUBY_ECONV_NEWLINE_DECORATOR_READ_MASK
(Unclear; seems unused).
Definition transcode.h:485
RUBY_ECONV_CR_NEWLINE_DECORATOR
@ RUBY_ECONV_CR_NEWLINE_DECORATOR
CRLF to CR conversion shall happen.
Definition transcode.h:497
rb_econv_prepare_options
int rb_econv_prepare_options(VALUE opthash, VALUE *ecopts, int ecflags)
Identical to rb_econv_prepare_opts(), except it additionally takes the initial value of flags.
Definition transcode.c:2600
rb_econv_open_exc
VALUE rb_econv_open_exc(const char *senc, const char *denc, int ecflags)
Creates a rb_eConverterNotFoundError exception object (but does not raise).
Definition transcode.c:2097
rb_econv_encoding_to_insert_output
const char * rb_econv_encoding_to_insert_output(rb_econv_t *ec)
Queries an encoding name which best suits for rb_econv_insert_output()'s last parameter.
Definition transcode.c:1532
rb_econv_prepare_opts
int rb_econv_prepare_opts(VALUE opthash, VALUE *ecopts)
Splits a keyword arguments hash (that for instance String#encode took) into a set of enum ruby_econv_...
Definition transcode.c:2645
rb_econv_convert
rb_econv_result_t rb_econv_convert(rb_econv_t *ec, const unsigned char **source_buffer_ptr, const unsigned char *source_buffer_end, unsigned char **destination_buffer_ptr, unsigned char *destination_buffer_end, int flags)
Converts a string from an encoding to another.
Definition transcode.c:1475
rb_econv_result_t
rb_econv_result_t
return value of rb_econv_convert()
Definition transcode.h:30
econv_incomplete_input
@ econv_incomplete_input
The conversion stopped in middle of reading a character, possibly due to a partial read of a socket e...
Definition transcode.h:69
econv_finished
@ econv_finished
The conversion stopped after converting everything.
Definition transcode.h:57
econv_undefined_conversion
@ econv_undefined_conversion
The conversion stopped when it found a character in the input which cannot be representable in the ou...
Definition transcode.h:41
econv_after_output
@ econv_after_output
The conversion stopped after writing something to somewhere, before reading everything.
Definition transcode.h:63
econv_source_buffer_empty
@ econv_source_buffer_empty
The conversion stopped because there is no input.
Definition transcode.h:51
econv_destination_buffer_full
@ econv_destination_buffer_full
The conversion stopped because there is no destination.
Definition transcode.h:46
econv_invalid_byte_sequence
@ econv_invalid_byte_sequence
The conversion stopped when it found an invalid sequence.
Definition transcode.h:35
rb_econv_putbackable
int rb_econv_putbackable(rb_econv_t *ec)
Queries if rb_econv_putback() makes sense, i.e.
Definition transcode.c:1770
rb_econv_has_convpath_p
int rb_econv_has_convpath_p(const char *from_encoding, const char *to_encoding)
Queries if there is more than one way to convert between the passed two encodings.
Definition transcode.c:3211
rb_econv_open
rb_econv_t * rb_econv_open(const char *source_encoding, const char *destination_encoding, int ecflags)
Creates a new instance of struct rb_econv_t.
Definition transcode.c:1098
rb_econv_str_append
VALUE rb_econv_str_append(rb_econv_t *ec, VALUE src, VALUE dst, int flags)
Identical to rb_econv_str_convert(), except it appends the conversion result to the additionally pass...
Definition transcode.c:1919
rb_econv_substr_append
VALUE rb_econv_substr_append(rb_econv_t *ec, VALUE src, long byteoff, long bytesize, VALUE dst, int flags)
Identical to rb_econv_str_append(), except it appends only a part of the passed string with conversio...
Definition transcode.c:1910
rb_econv_asciicompat_encoding
const char * rb_econv_asciicompat_encoding(const char *encname)
Queries the passed encoding's corresponding ASCII compatible encoding.
Definition transcode.c:1814
rb_econv_insert_output
int rb_econv_insert_output(rb_econv_t *ec, const unsigned char *str, size_t len, const char *str_encoding)
Appends the passed string to the passed converter's output buffer.
Definition transcode.c:1616
rb_econv_str_convert
VALUE rb_econv_str_convert(rb_econv_t *ec, VALUE src, int flags)
Identical to rb_econv_convert(), except it takes Ruby's string instead of C's pointer.
Definition transcode.c:1931
rb_econv_open_opts
rb_econv_t * rb_econv_open_opts(const char *source_encoding, const char *destination_encoding, int ecflags, VALUE ecopts)
Identical to rb_econv_open(), except it additionally takes a hash of optional strings.
Definition transcode.c:2651
rb_econv_decorate_at_last
int rb_econv_decorate_at_last(rb_econv_t *ec, const char *decorator_name)
Identical to rb_econv_decorate_at_first(), except it adds to the opposite direction.
Definition transcode.c:1979
rb_econv_binmode
void rb_econv_binmode(rb_econv_t *ec)
This badly named function does not set the destination encoding to binary, but instead just nullifies...
Definition transcode.c:1996
rb_econv_decorate_at_first
int rb_econv_decorate_at_first(rb_econv_t *ec, const char *decorator_name)
"Decorate"s a converter.
Definition transcode.c:1962
rb_str_encode
VALUE rb_str_encode(VALUE str, VALUE to, int ecflags, VALUE ecopts)
Converts the contents of the passed string from its encoding to the passed one.
Definition transcode.c:2914
rb_econv_make_exception
VALUE rb_econv_make_exception(rb_econv_t *ec)
This function makes sense right after rb_econv_convert() returns.
Definition transcode.c:4272
rb_econv_check_error
void rb_econv_check_error(rb_econv_t *ec)
This is a rb_econv_make_exception() + rb_exc_raise() combo.
Definition transcode.c:4278
rb_econv_substr_convert
VALUE rb_econv_substr_convert(rb_econv_t *ec, VALUE src, long byteoff, long bytesize, int flags)
Identical to rb_econv_str_convert(), except it converts only a part of the passed string.
Definition transcode.c:1925
rb_econv_close
void rb_econv_close(rb_econv_t *ec)
Destructs a converter.
Definition transcode.c:1731
rb_econv_append
VALUE rb_econv_append(rb_econv_t *ec, const char *bytesrc, long bytesize, VALUE dst, int flags)
Converts the passed C's pointer according to the passed converter, then append the conversion result ...
Definition transcode.c:1847
rb_econv_putback
void rb_econv_putback(rb_econv_t *ec, unsigned char *p, int n)
Puts back the bytes.
Definition transcode.c:1781
rb_econv_set_replacement
int rb_econv_set_replacement(rb_econv_t *ec, const unsigned char *str, size_t len, const char *encname)
Assigns the replacement string.
Definition transcode.c:2259
ruby_econv_flag_type
ruby_econv_flag_type
This enum is kind of omnibus.
Definition transcode.h:452
len
int len
Length of the buffer.
Definition io.h:8
rb_econv_t
Definition transcode.c:130
value.h
Defines VALUE and ID.
VALUE
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40