Changeset 150 for trunk/SRC/ToBeReviewed/STRUCTURE

Timestamp:

08/09/06 12:12:54 (18 years ago)

Author:

navarro

Message:

english and nicer header (3a)

Location:

trunk/SRC/ToBeReviewed/STRUCTURE

Files:

• chkstru.pro (modified) (2 diffs)
• extractstru.pro (modified) (4 diffs)
• mixstru.pro (modified) (2 diffs)
• struct2string.pro (modified) (2 diffs)
• where_tag.pro (modified) (2 diffs)

trunk/SRC/ToBeReviewed/STRUCTURE/chkstru.pro

@@ -1 @@
-; $Id$
 ;-------------------------------------------------------------
 ;+
-; NAME:
-;        CHKSTRU  (function)
+; @file_comments
+; check validity of a structure and test if necessary
+; fields are contained
 ;
-; PURPOSE:
-;        check validity of a structure and test if necessary
-;        fields are contained
+; @categories
+; tools
 ;
-; CATEGORY:
-;        tools
+; @param  STRUCTURE {in}{required}
+; The structure to be tested. If STRUCTURE is
+; not of type structure, the function will return 0
 ;
-; CALLING SEQUENCE:
-;        res=CHKSTRU(STRUCTURE,FIELDS [,/VERBOSE]) 
+; @param FIELDS {in}{required}
+; A string or string array with field names to 
+; be contained in STRUCTURE. CHKSTRU returns 1 (true)
+; only if all field names are contained in STRUCTURE.
+; The entries of FIELDS may be upper or lowercase.
 ;
-; INPUTS:
-;        STRUCTURE --> the structure to be tested. If STRUCTURE is
-;             not of type structure, the function will return 0
+; @keyword INDEX
+; A named variable that will contain the indices of
+; the required field names in the structure. They can then
+; be assessed through structure.(index[i]) . Index will
+; contain -1 for all fields entries that are not in the
+; structure.
 ;
-;        FIELDS --> a string or string array with field names to 
-;             be contained in STRUCTURE. CHKSTRU returns 1 (true)
-;             only if all field names are contained in STRUCTURE.
-;             The entries of FIELDS may be upper or lowercase.
+; @keyword VERBOSE
+; set this keyword to return an error message 
+; in case of an error.
 ;
-; KEYWORD PARAMETERS:
-;        INDEX --> a named variable that will contain the indices of
-;             the required field names in the structure. They can then
-;             be assessed through structure.(index[i]) . Index will
-;             contain -1 for all fields entries that are not in the
-;             structure.
+; @keyword EXTRACT
+; set this keyword to extract a fields from the
+; structure.  -1 is return is fields or structure. are
+; incorrect.
 ;
-;        /VERBOSE --> set this keyword to return an error message 
-;             in case of an error.
+; @returns
+; CHKSTRU returns 1 if successful, otherwise 0.
 ;
-;        /EXTRACT --> set this keyword to extract a fields from the
-;        structure.  -1 is return is fields or structure. are
-;        incorrect.
-;
-; OUTPUTS:
-;        CHKSTRU returns 1 if successful, otherwise 0.
-;
-; SUBROUTINES:
-;
-; REQUIREMENTS:
-;
-; NOTES:
-;
-; EXAMPLE:
+; @examples
 ;        test = { a:1, b:2, c:3 }
 ;        required = ['a','c']
@@ -56 +46 @@
 ;               2
 ;
-; MODIFICATION HISTORY:
+; @history
 ;        mgs, 02 Mar 1998: VERSION 1.00
 ;        mgs, 07 Apr 1998: - second parameter (FIELDS) now optional
 ;        12 Jan 2001: EXTRACT keyword by S. Masson (smasson@lodyc.jussieu.fr) 
+;
+; @version
+; $Id$
 ;
 ;-

trunk/SRC/ToBeReviewed/STRUCTURE/extractstru.pro

@@ -3 +3 @@
 ;------------------------------------------------------------
 ;+
-; NAME:extractstru
+; @file_comments
+; extract elements of a structure to constitute a new structure.
 ;
-; PURPOSE:extrait des elements d''une structure pour constituer une
-;         nouvelle structure
+; @categories
+; utilities
 ;
-; CATEGORY: dibouille sur les structures
+; @param STRU {in}{required}
+; A structure
 ;
-; CALLING SEQUENCE: res = extractstru(stru, liste)
-; 
-; INPUTS:
+; @param LISTE {in}{required}
+; A vector of string including names of STRU to be deleted 
+; (by default) or to be kept (if KEEP is activated).
 ;
-;    stru: une structure
+; @keyword KEEP
+; Specify that the given liste concern elements of STRU to be kept.
 ;
-;    liste: un vecteur de string comportant les noms des elements de
-;    stru a virer (par DEFAUT) ou a garder (si GARDE est active)
+; @keyword DELETE:
+; Specify  that the given liste concern elements of STRU to be deleted.
+; This keyword is activated by default.
 ;
-; KEYWORD PARAMETERS:
+; @returns
+; A structure or -1 in case of problem
 ;
-;    /GARDE: specifie que la liste donnee concerne les elements de
-;    stru a garder
-;
-;    /VIRE: specifie que la liste donnee concerne les elements de
-;    stru a virer. Ce mot cle est active par defaut
-;
-; OUTPUTS:une stucture ou -1 en cas de pb
-;
-; COMMON BLOCKS:
-;
-; SIDE EFFECTS:
-;
-; RESTRICTIONS: none !!!
-;    liste peut contenir des noms d''elements qui ne sont pas ds stru,
-;    le programme se debrouille avec
-;
-; EXAMPLE:
+; @examples
 ;
 ;    IDL> extra=get_extra(/ok, year=1999, age_capitaine=35 )
@@ -48 +37 @@
 ;    ** Structure <831afac>, 1 tags, length=2, refs=1:
 ;       AGE_CAPITAINE   INT             35
-;    IDL> help, extractstru(extra,['ok','hhuihi','YEAR'],/garde),/stru
+;    IDL> help, extractstru(extra,['ok','hhuihi','YEAR'],/keep),/stru
 ;    ** Structure <834bbc4>, 2 tags, length=4, refs=1:
 ;       OK              INT              1
 ;       YEAR            INT           1999
 ;
-; MODIFICATION HISTORY:Sebastien Masson (smasson@lodyc.jussieu.fr)
+; @history
+; Sebastien Masson (smasson@lodyc.jussieu.fr)
 ;                      8/10/1999
+;
+; @version
+; $Id$
+; 
 ;-
 ;------------------------------------------------------------
 ;------------------------------------------------------------
 ;------------------------------------------------------------
-FUNCTION extractstru, stru, liste, GARDE = garde, VIRE = vire
+FUNCTION extractstru, stru, liste, KEEP = keep, DELETE = delete
 ;
   compile_opt idl2, strictarrsubs
@@ -65 +59 @@
    if size(stru, /type) NE 8 then return,  -1
    if size(liste, /type) NE 7 then return,  -1
-; cheking for garde and vire keywords
-   garde = keyword_set(garde)*(1-keyword_set(vire))
-   vire = keyword_set(vire)*(1-keyword_set(garde)) +(keyword_set(vire) EQ garde)
+; cheking for keep and vire keywords
+   keep = keyword_set(keep)*(1-keyword_set(delete))
+   delete = keyword_set(delete)*(1-keyword_set(keep)) +(keyword_set(delete) EQ keep)
 ;
    tname = tag_names(stru)
    index = make_selection(tname, strupcase(liste), /only_valid, /quiet)
 ;
-   if garde then BEGIN ; on garde que la liste
+   if keep then BEGIN ; We just keep the list
       if index[0] EQ -1 then return,  -1
       if n_elements(index) EQ n_elements(tname) then return, stru
@@ -78 +72 @@
       if n_elements(index) GT 1 then for i = 1, n_elements(index)-1 do $
             res = create_struct(res, tname[index[i]], stru.(index[i]))
-   ENDIF ELSE BEGIN ; on vire la liste
+   ENDIF ELSE BEGIN ; We delete the list
       if n_elements(index) EQ n_elements(tname) then return,  -1
       if index[0] EQ -1 then return, stru
-; on prend le complementaire de index pour obtenir les indices que
-; l''on garde
+; We take the complementary one of index to obtain indexes we keep.
       index = different(indgen(n_elements(tname)), index)
       res = create_struct(tname[index[0]], stru.(index[0]))

trunk/SRC/ToBeReviewed/STRUCTURE/mixstru.pro

@@ -3 +3 @@
 ;------------------------------------------------------------
 ;+
-; NAME: mixstru
 ;
-; PURPOSE: concatene 2 structures ensemble. La difference avec
-; CREATE_STRUCT etant que si les 2 stuctures ont les memes noms
-; d''elements alors mixstru ne plante pas mais choisit pour valeur de
-; l''element commun celle specifiee par la premiere structure.
+; @file_comments
+; Concatenate 2 structures together. The difference with CREATE_STRUCT 
+; is  that if the 2 structure have same elements's name, then mixstru 
+; do not break down but choose for the common element the value 
+; specified by the first structure.
 ;
-; CATEGORY: structure
+; @categories
+; structure
+; 
+; @param STRU1 {in}{required}
+; Structure which can have same elements's name than 
+; STRU2 but with a different value.
 ;
-; CALLING SEQUENCE: rs=mixstru(stru1,stru2)
-; 
-; INPUTS: stru1 et stu2 sont 2 structures qui peuvent avoir des
-; elements portant le meme nom mais avec une valeur differente.
+; @param STRU2 {in}{required}
+; Structure which can have same elements's name than 
+; STRU1 but with a different value.
 ;
-; KEYWORD PARAMETERS: none
+; @returns
+; A stucture
 ;
-; OUTPUTS: une stucture
+; @restrictions
+; If STRU1 or  STRU2 is not a structure, mixstru send back -1
 ;
-; COMMON BLOCKS:
-;
-; SIDE EFFECTS: si stru1 ou stru2 ne sont pas des structures mixstru
-; renvoie -1
-;
-; RESTRICTIONS:
-;
-; EXAMPLE:
+; @examples
 ;     
 ;     IDL> a=get_extra(/toto,ok=123)
@@ -53 +52 @@
 ;        YEAR            INT           1999
 ;
-; MODIFICATION HISTORY:Sebastien Masson (smasson@lodyc.jussieu.fr)
+; @history
+; Sebastien Masson (smasson@lodyc.jussieu.fr)
 ;                      7/10/1999
+;
+; @version
+; $Id$
+;
 ;-
 ;------------------------------------------------------------

trunk/SRC/ToBeReviewed/STRUCTURE/struct2string.pro

@@ -3 +3 @@
 ;------------------------------------------------------------
 ;+
-; NAME:struct2string
+; 
+; @file_comments
+; Convert a structure to an "executable string"
 ;
-; PURPOSE:convert a structure to an "executable string"
+; @categories
+; utilities
+; 
+; @param STRUCT {in}{required}
+; A structure
 ;
-; CATEGORY:bidouille
+; @keyword MAX_STRUCT_LENGTH
+; The maximum length of the structure
+; permetted to convert the structure to string. Default is
+; 10000l.
 ;
-; CALLING SEQUENCE:sting=struct2string(struct)
-; 
-; INPUTS:struct: a structure
+; @keyword DIRECT2STRING
+; To get a string instead an "executable string"
 ;
-; KEYWORD PARAMETERS:
+; @keyword CUT_IN_STRING
+; Try it
 ;
-;      MAX_STRUCT_LENGTH : the maximum length of the structure
-;      permetted to convert the structure to string. Default is
-;      10000l.
+; @restrictions
+; Use tostr.pro, cf this function header!
 ;
-;      /DIRECT2STRING: to get a string instead an "executable string"
-;
-;      /CUT_IN_STRING: try it
-;
-; OUTPUTS:
-;
-; SIDE EFFECTS:use tostr.pro, cf this function header!
-;
-; RESTRICTIONS:use tostr.pro, cf this function header!
-;
-; EXAMPLE:
+; @examples
 ;
 ;      IDL> print, struct2string(!d)
@@ -38 +36 @@
 ;      ,[0,0],'ZOOM',[1,1])
 ;
-; MODIFICATION HISTORY:Sebastien Masson (smasson@lodyc.jussieu.fr)
+; @history
+; Sebastien Masson (smasson@lodyc.jussieu.fr)
 ;                      2000 07 03
+;
+; @version
+; $Id$
+;
 ;-
 ;------------------------------------------------------------

trunk/SRC/ToBeReviewed/STRUCTURE/where_tag.pro

@@ -1 +1 @@
 ;+
-; NAME:
-;       WHERE_TAG
-; PURPOSE:
-;       Like WHERE but works on structure tag names
-; EXPLANATION:
-;       Obtain subscripts of elements in structure array for which
-;       a particular Tag has values in a range or matching specified values.
-;       Like the WHERE function but for use with structures
-; CATEGORY:
-;                       Structures
-; CALLING SEQUENCE:
-;        w = where_tag( struct, [ Nfound,  TAG_NAME=, TAG_NUMBER = , RANGE =, 
-;                               VALUES =, RANGE =, ISELECT =, /NOPRINT ]
+; @file_comments
+; Like WHERE but works on structure tag names
+; Obtain subscripts of elements in structure array for which
+; a particular Tag has values in a range or matching specified values.
+; Like the WHERE function but for use with structures
+; 
+; @categories
+; Structures
 ;
-; INPUTS:
-;       Struct = structure array to search.
+; @param STRUCT {in}{required}
+; structure array to search.
 ;
-; INPUT KEYWORDS:
-;       User *must* specify (1) TAG_NAME or TAG_NUMBER to search, and (2)
-;               the VALUES or RANGE to search on
+; @keyword TAG_NAME
+; Scalar string specifying Tag Name
+; 
+; @keyword TAG_NUMBER
+; Otherwise give the Tag Number,
+; 
+; @keyword RANGE
+;  [min,max] range to search for in Struct
+; 
+; @keyword VALUES
+; One or array of numbers to match for in Struct,
+; 
+; @keyword ISELECT
+; Specifies indices to select only part of structure array,
+; (use it to recycle subscripts from previous searches).
+; 
+; @keyword NOPRINT
+; Suppress informational messages about nothing found.
 ;
-;       TAG_NAME = Scalar string specifying Tag Name
-;       TAG_NUMBER = otherwise give the Tag Number,
-;       RANGE = [min,max] range to search for in Struct,
-;       VALUES = one or array of numbers to match for in Struct,
-;       ISELECT= specifies indices to select only part of structure array,
-;               (use it to recycle subscripts from previous searches).
-;       /NOPRINT = suppress informational messages about nothing found.
+; @returns
+; Nfound {out}
+; # of occurences found.
+; 
+; @restrictions
+; User *must* specify (1) TAG_NAME or TAG_NUMBER to search, and (2)
+; the VALUES or RANGE to search on;
 ;
-; OUTPUTS:
-;       Nfound = # of occurences found.
-;
-; RESULT:
-;       Function returns subscripts (indices) to desired elements.
-;
-; EXAMPLES:
+; @examples
 ;       Suppose STR is a structure with tags CAT_NO:indgen(10), and 
 ;               NAME:strarr(10).   Find the indices where STR.CAT_NO is
@@ -43 +47 @@
 ;       IDL> print, WHERE_TAG( str, TAG_NUM = 0, RANGE = [3,5]) 
 ;
-; PROCEDURE:
-;       Get tag number and apply the WHERE function appropriately.
-;
-; MODIFICATION HISTORY:
+; @history
 ;       written 1990 Frank Varosi STX @ NASA/GSFC
 ;       Stop printing "Tag <xxx> not found" with /NOPRINT, CD Pike 8-Jun-93
+;
+; @version
+; $Id$
+; 
 ;-
 function where_Tag, Struct, Nfound,     TAG_NAME=Tag_Name,      $