; docformat = 'rst' ;+ ; Class representing a string and an example of using operator overloading ; available in IDL 8.0. ; This class does not require IDL 8.0 to compile because an IDL_Object class ; (which this class inherits from) is provided. Operator overloading will not ; be available when using IDL versions before 8.0, but the methods could be ; called directly. ; ; :Properties: ; length ; length of the string ;- ;+ ; Get properties. ; ; :Examples: ; Properties can be access with `.` in IDL 8.0:: ; ; IDL> s = mg_string('Hello, World!') ; IDL> print, s.length ; 13 ;- pro mg_string::getProperty, length=length compile_opt strictarr if (arg_present(length)) then length = strlen(self.s) end ;+ ; Returns the underlying IDL string. ; ; :Returns: ; string ;- function mg_string::toString compile_opt strictarr return, self.s end ;+ ; Called when a string object is accessed with the square brackets, i.e., ; `[]`. ; ; :Examples: ; For example:: ; ; IDL> s = mg_string('Hello, World!') ; IDL> print, s[0] ; H ; IDL> print, s[0:4] ; Hello ; ; :Returns: ; IDL string ; ; :Params: ; isRange : in, required, type=lonarr(1..8) ; array of the same length as the number of dimensions indexed in the ; bracket expression ; ss1 : in, required, type=long or lonarr(3) ; index or range of characters to extract ; ss2 : in, optional, type=long or lonarr(3) ; not used for strings ; ss3 : in, optional, type=long or lonarr(3) ; not used for strings ; ss4 : in, optional, type=long or lonarr(3) ; not used for strings ; ss5 : in, optional, type=long or lonarr(3) ; not used for strings ; ss6 : in, optional, type=long or lonarr(3) ; not used for strings ; ss7 : in, optional, type=long or lonarr(3) ; not used for strings ; ss8 : in, optional, type=long or lonarr(3) ; not used for strings ;- function mg_string::_overloadBracketsRightSide, isRange, ss1, ss2, ss3, ss4, $ ss5, ss6, ss7, ss8 compile_opt strictarr if (isRange[0]) then begin return, mg_string((byte(self.s))[ss1[0]:ss1[1]:ss1[2]]) endif else begin return, mg_string((byte(self.s))[ss1]) endelse end ;+ ; Called when the two strings or string objects are joined using a format code ; by the `#` operator. ; ; :Examples: ; For example:: ; ; IDL> print, mg_string('Location: %s') # 'Boulder, CO' ; Location: Boulder, CO ; IDL> print, 'Location: %s' # mg_string('Boulder, CO') ; Location: Boulder, CO ; ; :Returns: ; string object ; ; :Params: ; left : in, required, type=string or string object ; string on the left of the # operator ; right : in, required, type=string or string object ; string on the right of the # operator ;- function mg_string::_overloadPound, left, right compile_opt strictarr _left = obj_valid(left) ? left->toString() : left _right = obj_valid(right) ? right->toString() : right return, mg_string(_right, format='(%"' + _left + '")') end ;+ ; Called when two strings or strings objects are concatenated with the `+` ; operator. ; ; :Examples: ; For example:: ; ; IDL> s1 = mg_string('Hello') ; IDL> s2 = mg_string('World!') ; IDL> print, s1 + s2 ; HelloWorld! ; IDL> print, s1 + ", " + s2 ; Hello, World! ; ; :Returns: ; string object ; ; :Params: ; left : in, required, type=string or string object ; string on the left of the + operator ; right : in, required, type=string or string object ; string on the right of the + operator ;- function mg_string::_overloadPlus, left, right compile_opt strictarr _left = obj_valid(left) ? left->toString() : left _right = obj_valid(right) ? right->toString() : right return, mg_string(_left + _right) end ;+ ; Called by the `HELP` routine when information about this object is required. ; ; :Examples: ; For example:: ; ; IDL> s = mg_string('Hello, World!') ; IDL> help, s ; S MG_STRING = 'Hello, World!' ; ; :Returns: ; string ; ; :Params: ; varname : in, required, type=string ; name of the variable at the level where `HELP` was called ;- function mg_string::_overloadHelp, varname compile_opt strictarr return, string(varname, 'MG_STRING', self->toString(), $ format='(%"%-15s %-9s = ''%s''")') end ;+ ; Called by the `PRINT` routine when this object is printed. ; ; :Examples: ; For example:: ; ; IDL> s = mg_string('Hello, World!') ; IDL> print, s ; Hello, World! ; ; :Returns: ; string ;- function mg_string::_overloadPrint compile_opt strictarr return, self->toString() end ;+ ; Called by the `FOREACH` routine when this object is looped over. ; ; :Examples: ; For example:: ; ; :Returns: ; 1 if there are more characters in the string, 0 if not ; ; :Params: ; value : out, required, type=string ; character returned as the next character in the string ; key : in, out, optional, type=undefined/long ; index of current position in the string; undefined for starting ;- function mg_string::_overloadForeach, value, key compile_opt strictarr key = n_elements(key) eq 0L ? 0L : (key + 1L) status = key lt strlen(self.s) if (status) then value = strmid(self.s, key, 1L) return, status end ;+ ; Initialize the object. ; ; :Returns: ; 1 if successful, 0 if not ; ; :Params: ; str : in, required, type=string ; IDL string to represent ; ; :Keywords: ; format : in, optional, type=string ; format string as expected by STRING routine ;- function mg_string::init, str, format=format compile_opt strictarr self.s = string(str, format=format) return, 1 end ;+ ; Define instance variables. ; ; :Fields: ; s ; IDL string containing the string to represent ;- pro mg_string__define compile_opt strictarr define = { MG_String, inherits IDL_Object, s: '' } end