lib/core/codecs/codec_base.nit

   1 # This file is part of NIT (http://www.nitlanguage.org).
   2 #
   3 # Licensed under the Apache License, Version 2.0 (the "License");
   4 # you may not use this file except in compliance with the License.
   5 # You may obtain a copy of the License at
   6 #
   7 #        http://www.apache.org/licenses/LICENSE-2.0
   8 #
   9 # Unless required by applicable law or agreed to in writing, software
  10 # distributed under the License is distributed on an "AS IS" BASIS,
  11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 # See the License for the specific language governing permissions and
  13 # limitations under the License.
  14
  15 # Base for codecs to use with streams
  16 #
  17 # A Codec (Coder/Decoder) is a tranformer from a byte-format to another
  18 #
  19 # As Nit Strings are UTF-8, a codec works as :
  20 # - Coder: From a UTF-8 string to a specified format (writing)
  21 # - Decoder: From a specified format to a UTF-8 string (reading)
  22 module codec_base
  23
  24 import text
  25 import bytes
  26
  27 # Codes/Decodes entities from/to UTF-8
  28 abstract class Codec
  29         # Maximum size of a `character` in supported encoding
  30         fun char_max_size: Int is abstract
  31
  32         # Transforms `c` to its representation in the format of `self`
  33         fun encode_char(c: Char): CString is abstract
  34
  35         # Adds a char `c` to bytes `s`
  36         #
  37         # Returns the number of bytes written to `s`
  38         fun add_char_to(c: Char, s: CString): Int is abstract
  39
  40         # Transforms `s` to the format of `self`
  41         fun encode_string(s: Text): Bytes is abstract
  42
  43         # Adds a string `s` coded as the supported encoding to `b`
  44         #
  45         # Returns the number of bytes written to `s`
  46         fun add_string_to(s: Text, b: Bytes): Int is abstract
  47
  48         # Size of a codet for the target encoding
  49         fun codet_size: Int is abstract
  50
  51         # How many lookaheads might be required to decode a single char ?
  52         fun max_lookahead: Int is abstract
  53
  54         # Is the sequence of bytes in `ns` at `position` a valid Char ?
  55         #
  56         # Returns either
  57         # * 0 if valid
  58         # * 1 if incomplete
  59         # * 2 if invalid
  60         fun is_valid_char(ns: CString, position: Int): Int is abstract
  61
  62         # Decodes a char from `b` to a Unicode code-point
  63         fun decode_char(b: CString): Char is abstract
  64
  65         # Decodes a string `b` to UTF-8
  66         fun decode_string(b: CString, len: Int): String is abstract
  67 end