dicom 0.9.7 → 0.9.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c471922e97e22ce893a34540e6e329f1bfb758ab
-  data.tar.gz: 9772c5dc74910531dbc740dda4966ac7056f36e3
+  metadata.gz: f91db23166e9a16c8cd6b4d694b7aa530e39b143
+  data.tar.gz: 76edf3567fb40346cc0ab81d2c6dced7efcdd556
 SHA512:
-  metadata.gz: e87bde50743b0ab641bd6087a43ef8da3adaac446baf2f0c14c1f439475a05e7df0c5af4b6d96d5668f60fd0ad651e49a4309e89c7c90536564d353505f8e62d
-  data.tar.gz: 01239e3b7957ebcc2f663427889057c158bf3247f00868ac2045cc6ab0a1f7e8aa218f2395c77f3a88ee6ca7807ddca0bc553a2f1d22e5053ee9a2157ced0d73
+  metadata.gz: c39d93a981235ff3e63d80108d18c043ebd7ba12f161eb5791a5807ae297bb6f5a0f5b8aca364c6a0bdfd1e5036172553ebb3d2c0a609cddb43831ad0b92500a
+  data.tar.gz: 6be61b879bf566c73285f370da46241576ee3231d4b3e446c90512d7740c74564bcb6f312fa64dcb8a24df95ef43542736595a844ab6f34b95b0555e9272349e

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+# 0.9.8
+
+## 24th March, 2018
+
+* Changed: Replaced Fixnum with Integer to avoid deprecation warning in Ruby 2.4.
+* Changed: Replaced NArray with Numo/Narray.
+* Fixed: Improved compatibility with Japanese string encoding.
+
+
 # 0.9.7
 
 ## 4th January, 2017

data/Gemfile.lock

@@ -1,49 +1,49 @@
 PATH
   remote: .
   specs:
-    dicom (0.9.7)
+    dicom (0.9.8)
 
 GEM
   remote: http://www.rubygems.org/
   specs:
     diff-lcs (1.2.5)
     metaclass (0.0.4)
-    mini_magick (4.4.0)
-    mocha (1.1.0)
+    mini_magick (4.8.0)
+    mocha (1.4.0)
       metaclass (~> 0.0.1)
-    narray (0.6.1.1)
-    rake (10.5.0)
-    redcarpet (3.3.3)
+    numo-narray (0.9.1.1)
+    rake (12.3.1)
+    redcarpet (3.4.0)
     rmagick (2.15.4)
-    rspec (3.4.0)
-      rspec-core (~> 3.4.0)
-      rspec-expectations (~> 3.4.0)
-      rspec-mocks (~> 3.4.0)
-    rspec-core (3.4.1)
-      rspec-support (~> 3.4.0)
-    rspec-expectations (3.4.0)
+    rspec (3.7.0)
+      rspec-core (~> 3.7.0)
+      rspec-expectations (~> 3.7.0)
+      rspec-mocks (~> 3.7.0)
+    rspec-core (3.7.1)
+      rspec-support (~> 3.7.0)
+    rspec-expectations (3.7.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.4.0)
-    rspec-mocks (3.4.0)
+      rspec-support (~> 3.7.0)
+    rspec-mocks (3.7.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.4.0)
-    rspec-support (3.4.0)
-    yard (0.8.7.6)
+      rspec-support (~> 3.7.0)
+    rspec-support (3.7.1)
+    yard (0.9.12)
 
 PLATFORMS
   x86-mingw32
 
 DEPENDENCIES
-  bundler (~> 1.11)
+  bundler (~> 1.16)
   dicom!
-  mini_magick (~> 4.4)
-  mocha (~> 1.1)
-  narray (~> 0.6, >= 0.6.1)
-  rake (~> 10.5)
-  redcarpet (~> 3.3)
+  mini_magick (~> 4.8)
+  mocha (~> 1.4)
+  numo-narray (~> 0.9, >= 0.9.1.1)
+  rake (~> 12.3)
+  redcarpet (~> 3.4)
   rmagick (~> 2.15)
-  rspec (~> 3.4)
-  yard (~> 0.8, >= 0.8.7)
+  rspec (~> 3.7)
+  yard (~> 0.9, >= 0.9.12)
 
 BUNDLED WITH
-   1.11.2
+   1.16.1

data/README.md

@@ -111,7 +111,7 @@ Example:
 
 ## COPYRIGHT
 
-Copyright 2008-2017 Christoffer Lervåg
+Copyright 2008-2018 Christoffer Lervåg
 
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
@@ -150,5 +150,6 @@ Please don't hesitate to email me if you have any feedback related to this proje
 * [Steven Bedrick](https://github.com/stevenbedrick)
 * [Lars Benner](https://github.com/Maturin)
 * [Brett Goulder](https://github.com/brettgoulder)
+* [Satoshi Funayama](https://github.com/akchan)
 * André Wuttke
 * Thomas Koschel

data/dicom.gemspec

@@ -19,13 +19,13 @@ Gem::Specification.new do |s|
 
   s.required_ruby_version = '>= 2.2.2'
 
-  s.add_development_dependency('bundler', '~> 1.11')
-  s.add_development_dependency('mini_magick', '~> 4.4')
-  s.add_development_dependency('mocha', '~> 1.1')
-  s.add_development_dependency('narray', '~> 0.6', '>= 0.6.1')
-  s.add_development_dependency('rake', '~> 10.5')
-  s.add_development_dependency('redcarpet', '~> 3.3')
+  s.add_development_dependency('bundler', '~> 1.16')
+  s.add_development_dependency('mini_magick', '~> 4.8')
+  s.add_development_dependency('mocha', '~> 1.4')
+  s.add_development_dependency('numo-narray', '~> 0.9', '>= 0.9.1.1')
+  s.add_development_dependency('rake', '~> 12.3')
+  s.add_development_dependency('redcarpet', '~> 3.4')
   s.add_development_dependency('rmagick', '~> 2.15')
-  s.add_development_dependency('rspec', '~> 3.4')
-  s.add_development_dependency('yard', '~> 0.8', '>= 0.8.7')
+  s.add_development_dependency('rspec', '~> 3.7')
+  s.add_development_dependency('yard', '~> 0.9', '>= 0.9.12')
 end

data/lib/dicom/anonymizer.rb

@@ -50,7 +50,7 @@ module DICOM
     # @option options [Boolean] :delete_private toggles whether private elements are to be deleted
     # @option options [TrueClass, Digest::Class] :encryption if set as true, the default hash function (MD5) will be used for representing DICOM values in an audit file. Otherwise a Digest class can be given, e.g. Digest::SHA256
     # @option options [Boolean] :enumeration toggles whether (some) elements get enumerated values (to enable post-anonymization re-identification)
-    # @option options [Fixnum] :logger_level the logger level which is applied to DObject operations during anonymization (defaults to Logger::FATAL)
+    # @option options [Integer] :logger_level the logger level which is applied to DObject operations during anonymization (defaults to Logger::FATAL)
     # @option options [Boolean] :random_file_name toggles whether anonymized files will be given random file names when rewritten (in combination with the :write_path option)
     # @option options [Boolean] :recursive toggles whether to anonymize on all sub-levels of the DICOM object tag hierarchies
     # @option options [Boolean] :uid toggles whether UIDs will be replaced with custom generated UIDs (beware that to preserve UID relations in studies/series, the audit_trail feature must be used)
@@ -210,7 +210,7 @@ module DICOM
     #
     # @note Two objects with the same attributes will have the same hash code.
     #
-    # @return [Fixnum] the object's hash code
+    # @return [Integer] the object's hash code
     #
     def hash
       state.hash
@@ -471,7 +471,7 @@ module DICOM
     # a new enumerated replacement value is found by increasing an index by 1.
     #
     # @param [String, Integer, Float] original the original value of the tag to be anonymized
-    # @param [Fixnum] j the index of this tag in the tag-related instance arrays
+    # @param [Integer] j the index of this tag in the tag-related instance arrays
     # @return [String, Integer, Float] the replacement value which is used for the anonymization of the tag
     #
     def enumerated_value(original, j)

data/lib/dicom/d_object.rb

@@ -1,4 +1,4 @@
-#    Copyright 2008-2017 Christoffer Lervag
+#    Copyright 2008-2018 Christoffer Lervag
 #
 #    This program is free software: you can redistribute it and/or modify
 #    it under the terms of the GNU General Public License as published by
@@ -238,7 +238,7 @@ module DICOM
     #
     # @note Two objects with the same attributes will have the same hash code.
     #
-    # @return [Fixnum] the object's hash code
+    # @return [Integer] the object's hash code
     #
     def hash
       state.hash

data/lib/dicom/element.rb

@@ -1,278 +1,278 @@
-module DICOM
-
-  # The Element class handles information related to ordinary (non-parent) elementals (data elements).
-  #
-  class Element
-
-    # Include the Elemental mix-in module:
-    include Elemental
-
-    # Creates an Element instance.
-    #
-    # @note In the case where the Element is given a binary instead of value,
-    #   the Element will not have a formatted value (value = nil).
-    # @note Private data elements are named as 'Private'.
-    # @note Non-private data elements that are not found in the dictionary are named as 'Unknown'.
-    #
-    # @param [String] tag a ruby-dicom type element tag string
-    # @param [String, Integer, Float, Array, NilClass] value a custom value to be encoded as the data element binary string, or in some cases (specified by options), a pre-encoded binary string
-    # @param [Hash] options the options to use for creating the element
-    #
-    # @option options [String] :bin if you already have the value pre-encoded to a binary string, the string can be supplied with this option to avoid it being encoded a second time
-    # @option options [Boolean] :encoded if the value parameter contains a pre-encoded binary, this boolean must to be set as true
-    # @option options [String] :name the name of the Element (if not specified, the name is retrieved from the dictionary)
-    # @option options [DObject, Item, NilClass] :parent a parent instance (Item or DObject) which the element belongs to
-    # @option options [String] :vr if a private element is created with a custom value, this must be specified to enable the encoding of the value (if not specified, the vr is retrieved from the dictionary)
-    #
-    # @example Create a new data element and connect it to a DObject instance
-    #   patient_name = Element.new('0010,0010', 'John Doe', :parent => dcm)
-    # @example Create a "Pixel Data" element and insert image data that you have already encoded elsewhere
-    #   pixel_data = Element.new('7FE0,0010', processed_pixel_data, :encoded => true, :parent => dcm)
-    # @example Create a private data element
-    #   private = Element.new('0011,2102', some_data, :parent => dcm, :vr => 'LO')
-    #
-    def initialize(tag, value, options={})
-      raise ArgumentError, "The supplied tag (#{tag}) is not valid. The tag must be a string of the form 'GGGG,EEEE'." unless tag.is_a?(String) && tag.tag?
-      # Set instance variables:
-      @tag = tag.upcase
-      # We may need to retrieve name and vr from the library:
-      if options[:name] and options[:vr]
-        @name = options[:name]
-        @vr = options[:vr].upcase
-      else
-        name, vr = LIBRARY.name_and_vr(tag)
-        @name = options[:name] || name
-        @vr = (options[:vr] ? options[:vr].upcase : vr)
-      end
-      # Manage the parent relation if specified:
-      if options[:parent]
-        @parent = options[:parent]
-        # FIXME: Because of some implementation problems, attaching the special
-        # Data Set Trailing Padding element to a parent is not supported yet!
-        @parent.add(self, :no_follow => true) unless @tag == 'FFFC,FFFC' && @parent.is_a?(Sequence)
-      end
-      # Value may in some cases be the binary string:
-      unless options[:encoded]
-        # The Data Element may have a value, have no value and no binary, or have no value and only binary:
-        if value
-          # Is binary value provided or do we need to encode it?
-          if options[:bin]
-            @value = value
-            @bin = options[:bin]
-          else
-            if value == ''
-              @value = value
-              @bin = ''
-            else
-              # Set the value with our custom setter method to get proper encoding:
-              self.value = value
-            end
-          end
-        else
-          # When no value is present, we set the binary as an empty string, unless the binary is specified:
-          @bin = options[:bin] || ''
-        end
-      else
-        @bin = value
-      end
-      # Let the binary decide the length:
-      @length = @bin.length
-    end
-
-    # Checks for equality.
-    #
-    # Other and self are considered equivalent if they are
-    # of compatible types and their attributes are equivalent.
-    #
-    # @param other an object to be compared with self.
-    # @return [Boolean] true if self and other are considered equivalent
-    #
-    def ==(other)
-      if other.respond_to?(:to_element)
-        other.send(:state) == state
-      end
-    end
-
-    alias_method :eql?, :==
-
-    # Sets the binary string of a Element.
-    #
-    # @note if the specified binary has an odd length, a proper pad byte will automatically be appended
-    #   to give it an even length (which is needed to conform with the DICOM standard).
-    #
-    # @param [String] new_bin a binary string of encoded data
-    #
-    def bin=(new_bin)
-      raise ArgumentError, "Expected String, got #{new_bin.class}." unless new_bin.is_a?(String)
-      # Add a zero byte at the end if the length of the binary is odd:
-      if new_bin.length.odd?
-        @bin = new_bin + stream.pad_byte[@vr]
-      else
-        @bin = new_bin
-      end
-      @value = nil
-      @length = @bin.length
-    end
-
-    # Checks if the Element actually has any child elementals.
-    #
-    # @return [FalseClass] always returns false, as Element instances by definition can't have children
-    #
-    def children?
-      return false
-    end
-
-    # Gives the endianness of the encoded binary value of this element.
-    #
-    # @return [Boolean] false if little endian, true if big endian
-    #
-    def endian
-      return stream.str_endian
-    end
-
-    # Computes a hash code for this object.
-    #
-    # @note Two objects with the same attributes will have the same hash code.
-    #
-    # @return [Fixnum] the object's hash code
-    #
-    def hash
-      state.hash
-    end
-
-    # Gives a string containing a human-readable hash representation of the Element.
-    #
-    # @return [String] a hash representation string of the element
-    #
-    def inspect
-      to_hash.inspect
-    end
-
-    # Checks if the Element is a parent.
-    #
-    # @return [FalseClass] always returns false, as Element instances by definition are not parents
-    #
-    def is_parent?
-      return false
-    end
-
-    # Creates a hash representation of the element instance.
-    #
-    # @note The key representation in this hash is configurable
-    #   (refer to the DICOM module methods documentation for more details).
-    # @return [Hash] a hash containing a key & value pair (e.g. {"Modality"=>"MR"})
-    #
-    def to_hash
-      return {self.send(DICOM.key_representation) => value}
-    end
-
-    # Returns self.
-    #
-    # @return [Element] self
-    #
-    def to_element
-      self
-    end
-
-    # Gives a json string containing a human-readable representation of the Element.
-    #
-    # @return [String] a string containing a key & value pair (e.g. "{\"Modality\":\"MR\"}")
-    #
-    def to_json
-      to_hash.to_json
-    end
-
-    # Gives a yaml string containing a human-readable representation of the Element.
-    #
-    # @return [String] a string containing a key & value pair (e.g. "---\nModality: MR\n")
-    #
-    def to_yaml
-      to_hash.to_yaml
-    end
-
-    # Gives the (decoded) value of the data element.
-    #
-    # @note Returned string values are automatically converted from their originally
-    #   encoding (e.g. ISO8859-1 or ASCII-8BIT) to UTF-8 for convenience reasons.
-    #   If the value string is wanted in its original encoding, extract the data
-    #   element's bin attribute instead.
-    #
-    # @note Note that according to the DICOM Standard PS 3.5 C.12.1.1.2, the Character Set only applies
-    # to values of data elements of type SH, LO, ST, PN, LT or UT. Currently in ruby-dicom, all
-    # string values are encoding converted regardless of VR, but whether this causes any problems is uknown.
-    #
-    # @return [String, Integer, Float] the formatted element value
-    #
-    def value
-      if @value.is_a?(String)
-        # Unless this is actually the Character Set data element,
-        # get the character set (note that it may not be available):
-        character_set = (@tag != '0008,0005' && top_parent.is_a?(DObject)) ? top_parent.value('0008,0005') : nil
-        # Convert to UTF-8 from [original encoding]:
-        # In most cases the original encoding is IS0-8859-1 (ISO_IR 100), but if
-        # it is not specified in the DICOM object, or if the specified string
-        # is not recognized, ASCII-8BIT is assumed.
-        @value.encode('UTF-8', ENCODING_NAME[character_set])
-        # If unpleasant encoding exceptions occur, the below version may be considered:
-        #@value.encode('UTF-8', ENCODING_NAME[character_set], :invalid => :replace, :undef => :replace)
-      else
-        @value
-      end
-    end
-
-    # Sets the value of the Element instance.
-    #
-    # In addition to updating the value attribute, the specified value is encoded to binary
-    # and used to update the Element's bin and length attributes too.
-    #
-    # @note The specified value must be of a type that is compatible with the Element's value representation (vr).
-    # @param [String, Integer, Float, Array] new_value a formatted value that is assigned to the element
-    #
-    def value=(new_value)
-      if VALUE_CONVERSION[@vr] == :to_s
-        # Unless this is actually the Character Set data element,
-        # get the character set (note that it may not be available):
-        character_set = (@tag != '0008,0005' && top_parent.is_a?(DObject)) ? top_parent.value('0008,0005') : nil
-        # Convert to [DObject encoding] from [input string encoding]:
-        # In most cases the DObject encoding is IS0-8859-1 (ISO_IR 100), but if
-        # it is not specified in the DICOM object, or if the specified string
-        # is not recognized, ASCII-8BIT is assumed.
-        @value = new_value.to_s.encode(ENCODING_NAME[character_set], new_value.to_s.encoding.name)
-        @bin = encode(@value)
-      else
-        # We may have an array (of numbers) which needs to be passed directly to
-        # the encode method instead of being forced into a numerical:
-        if new_value.is_a?(Array)
-          @value = new_value
-          @bin = encode(@value)
-        else
-          @value = new_value.send(VALUE_CONVERSION[@vr])
-          @bin = encode(@value)
-        end
-      end
-      @length = @bin.length
-    end
-
-
-    private
-
-
-    # Encodes a formatted value to a binary string.
-    #
-    # @param [String, Integer, Float, Array] formatted_value a formatted value
-    # @return [String] the encoded, binary string
-    #
-    def encode(formatted_value)
-      stream.encode_value(formatted_value, @vr)
-    end
-
-    # Collects the attributes of this instance.
-    #
-    # @return [Array<String>] an array of attributes
-    #
-    def state
-      [@tag, @vr, @value, @bin]
-    end
-
-  end
-end
+module DICOM
+
+  # The Element class handles information related to ordinary (non-parent) elementals (data elements).
+  #
+  class Element
+
+    # Include the Elemental mix-in module:
+    include Elemental
+
+    # Creates an Element instance.
+    #
+    # @note In the case where the Element is given a binary instead of value,
+    #   the Element will not have a formatted value (value = nil).
+    # @note Private data elements are named as 'Private'.
+    # @note Non-private data elements that are not found in the dictionary are named as 'Unknown'.
+    #
+    # @param [String] tag a ruby-dicom type element tag string
+    # @param [String, Integer, Float, Array, NilClass] value a custom value to be encoded as the data element binary string, or in some cases (specified by options), a pre-encoded binary string
+    # @param [Hash] options the options to use for creating the element
+    #
+    # @option options [String] :bin if you already have the value pre-encoded to a binary string, the string can be supplied with this option to avoid it being encoded a second time
+    # @option options [Boolean] :encoded if the value parameter contains a pre-encoded binary, this boolean must to be set as true
+    # @option options [String] :name the name of the Element (if not specified, the name is retrieved from the dictionary)
+    # @option options [DObject, Item, NilClass] :parent a parent instance (Item or DObject) which the element belongs to
+    # @option options [String] :vr if a private element is created with a custom value, this must be specified to enable the encoding of the value (if not specified, the vr is retrieved from the dictionary)
+    #
+    # @example Create a new data element and connect it to a DObject instance
+    #   patient_name = Element.new('0010,0010', 'John Doe', :parent => dcm)
+    # @example Create a "Pixel Data" element and insert image data that you have already encoded elsewhere
+    #   pixel_data = Element.new('7FE0,0010', processed_pixel_data, :encoded => true, :parent => dcm)
+    # @example Create a private data element
+    #   private = Element.new('0011,2102', some_data, :parent => dcm, :vr => 'LO')
+    #
+    def initialize(tag, value, options={})
+      raise ArgumentError, "The supplied tag (#{tag}) is not valid. The tag must be a string of the form 'GGGG,EEEE'." unless tag.is_a?(String) && tag.tag?
+      # Set instance variables:
+      @tag = tag.upcase
+      # We may need to retrieve name and vr from the library:
+      if options[:name] and options[:vr]
+        @name = options[:name]
+        @vr = options[:vr].upcase
+      else
+        name, vr = LIBRARY.name_and_vr(tag)
+        @name = options[:name] || name
+        @vr = (options[:vr] ? options[:vr].upcase : vr)
+      end
+      # Manage the parent relation if specified:
+      if options[:parent]
+        @parent = options[:parent]
+        # FIXME: Because of some implementation problems, attaching the special
+        # Data Set Trailing Padding element to a parent is not supported yet!
+        @parent.add(self, :no_follow => true) unless @tag == 'FFFC,FFFC' && @parent.is_a?(Sequence)
+      end
+      # Value may in some cases be the binary string:
+      unless options[:encoded]
+        # The Data Element may have a value, have no value and no binary, or have no value and only binary:
+        if value
+          # Is binary value provided or do we need to encode it?
+          if options[:bin]
+            @value = value
+            @bin = options[:bin]
+          else
+            if value == ''
+              @value = value
+              @bin = ''
+            else
+              # Set the value with our custom setter method to get proper encoding:
+              self.value = value
+            end
+          end
+        else
+          # When no value is present, we set the binary as an empty string, unless the binary is specified:
+          @bin = options[:bin] || ''
+        end
+      else
+        @bin = value
+      end
+      # Let the binary decide the length:
+      @length = @bin.length
+    end
+
+    # Checks for equality.
+    #
+    # Other and self are considered equivalent if they are
+    # of compatible types and their attributes are equivalent.
+    #
+    # @param other an object to be compared with self.
+    # @return [Boolean] true if self and other are considered equivalent
+    #
+    def ==(other)
+      if other.respond_to?(:to_element)
+        other.send(:state) == state
+      end
+    end
+
+    alias_method :eql?, :==
+
+    # Sets the binary string of a Element.
+    #
+    # @note if the specified binary has an odd length, a proper pad byte will automatically be appended
+    #   to give it an even length (which is needed to conform with the DICOM standard).
+    #
+    # @param [String] new_bin a binary string of encoded data
+    #
+    def bin=(new_bin)
+      raise ArgumentError, "Expected String, got #{new_bin.class}." unless new_bin.is_a?(String)
+      # Add a zero byte at the end if the length of the binary is odd:
+      if new_bin.length.odd?
+        @bin = new_bin + stream.pad_byte[@vr]
+      else
+        @bin = new_bin
+      end
+      @value = nil
+      @length = @bin.length
+    end
+
+    # Checks if the Element actually has any child elementals.
+    #
+    # @return [FalseClass] always returns false, as Element instances by definition can't have children
+    #
+    def children?
+      return false
+    end
+
+    # Gives the endianness of the encoded binary value of this element.
+    #
+    # @return [Boolean] false if little endian, true if big endian
+    #
+    def endian
+      return stream.str_endian
+    end
+
+    # Computes a hash code for this object.
+    #
+    # @note Two objects with the same attributes will have the same hash code.
+    #
+    # @return [Integer] the object's hash code
+    #
+    def hash
+      state.hash
+    end
+
+    # Gives a string containing a human-readable hash representation of the Element.
+    #
+    # @return [String] a hash representation string of the element
+    #
+    def inspect
+      to_hash.inspect
+    end
+
+    # Checks if the Element is a parent.
+    #
+    # @return [FalseClass] always returns false, as Element instances by definition are not parents
+    #
+    def is_parent?
+      return false
+    end
+
+    # Creates a hash representation of the element instance.
+    #
+    # @note The key representation in this hash is configurable
+    #   (refer to the DICOM module methods documentation for more details).
+    # @return [Hash] a hash containing a key & value pair (e.g. {"Modality"=>"MR"})
+    #
+    def to_hash
+      return {self.send(DICOM.key_representation) => value}
+    end
+
+    # Returns self.
+    #
+    # @return [Element] self
+    #
+    def to_element
+      self
+    end
+
+    # Gives a json string containing a human-readable representation of the Element.
+    #
+    # @return [String] a string containing a key & value pair (e.g. "{\"Modality\":\"MR\"}")
+    #
+    def to_json
+      to_hash.to_json
+    end
+
+    # Gives a yaml string containing a human-readable representation of the Element.
+    #
+    # @return [String] a string containing a key & value pair (e.g. "---\nModality: MR\n")
+    #
+    def to_yaml
+      to_hash.to_yaml
+    end
+
+    # Gives the (decoded) value of the data element.
+    #
+    # @note Returned string values are automatically converted from their originally
+    #   encoding (e.g. ISO8859-1 or ASCII-8BIT) to UTF-8 for convenience reasons.
+    #   If the value string is wanted in its original encoding, extract the data
+    #   element's bin attribute instead.
+    #
+    # @note Note that according to the DICOM Standard PS 3.5 C.12.1.1.2, the Character Set only applies
+    # to values of data elements of type SH, LO, ST, PN, LT or UT. Currently in ruby-dicom, all
+    # string values are encoding converted regardless of VR, but whether this causes any problems is uknown.
+    #
+    # @return [String, Integer, Float] the formatted element value
+    #
+    def value
+      if @value.is_a?(String)
+        # Unless this is actually the Character Set data element,
+        # get the character set (note that it may not be available):
+        character_set = (@tag != '0008,0005' && top_parent.is_a?(DObject)) ? top_parent.value('0008,0005') : nil
+        # Convert to UTF-8 from [original encoding]:
+        # In most cases the original encoding is IS0-8859-1 (ISO_IR 100), but if
+        # it is not specified in the DICOM object, or if the specified string
+        # is not recognized, ASCII-8BIT is assumed.
+        @value.encode('UTF-8', ENCODING_NAME[character_set])
+        # If unpleasant encoding exceptions occur, the below version may be considered:
+        #@value.encode('UTF-8', ENCODING_NAME[character_set], :invalid => :replace, :undef => :replace)
+      else
+        @value
+      end
+    end
+
+    # Sets the value of the Element instance.
+    #
+    # In addition to updating the value attribute, the specified value is encoded to binary
+    # and used to update the Element's bin and length attributes too.
+    #
+    # @note The specified value must be of a type that is compatible with the Element's value representation (vr).
+    # @param [String, Integer, Float, Array] new_value a formatted value that is assigned to the element
+    #
+    def value=(new_value)
+      if VALUE_CONVERSION[@vr] == :to_s
+        # Unless this is actually the Character Set data element,
+        # get the character set (note that it may not be available):
+        character_set = (@tag != '0008,0005' && top_parent.is_a?(DObject)) ? top_parent.value('0008,0005') : nil
+        # Convert to [DObject encoding] from [input string encoding]:
+        # In most cases the DObject encoding is IS0-8859-1 (ISO_IR 100), but if
+        # it is not specified in the DICOM object, or if the specified string
+        # is not recognized, ASCII-8BIT is assumed.
+        @value = new_value.to_s.encode(ENCODING_NAME[character_set], new_value.to_s.encoding.name)
+        @bin = encode(@value)
+      else
+        # We may have an array (of numbers) which needs to be passed directly to
+        # the encode method instead of being forced into a numerical:
+        if new_value.is_a?(Array)
+          @value = new_value
+          @bin = encode(@value)
+        else
+          @value = new_value.send(VALUE_CONVERSION[@vr])
+          @bin = encode(@value)
+        end
+      end
+      @length = @bin.length
+    end
+
+
+    private
+
+
+    # Encodes a formatted value to a binary string.
+    #
+    # @param [String, Integer, Float, Array] formatted_value a formatted value
+    # @return [String] the encoded, binary string
+    #
+    def encode(formatted_value)
+      stream.encode_value(formatted_value, @vr)
+    end
+
+    # Collects the attributes of this instance.
+    #
+    # @return [Array<String>] an array of attributes
+    #
+    def state
+      [@tag, @vr, @value, @bin]
+    end
+
+  end
+end