File IPNWB_Utils.ipf

Utility functions.

Functions

variable IsFinite(variable var)

Returns 1 if var is a finite/normal number, 0 otherwise.

variable IsNaN(variable var)

Returns 1 if var is a NaN, 0 otherwise.

variable isNull(string *str)

Returns 1 if str is null, 0 otherwise.

Parameters:

str – must not be a SVAR

variable isEmpty(string *str)

Returns one if str is empty or null, zero otherwise.

Parameters:

str – must not be a SVAR

variable DateTimeInUTC()

Return the seconds since Igor Pro epoch (1/1/1904) in UTC time zone.

variable IsInteger(variable var)

Returns one if var is an integer and zero otherwise.

string GetISO8601TimeStamp(variable secondsSinceIgorEpoch = defaultValue, variable numFracSecondsDigits = defaultValue, variable localTimeZone = defaultValue)

Return a string in ISO 8601 format with timezone UTC.

Parameters:

  • secondsSinceIgorEpoch – [optional, defaults to number of seconds until now] Seconds since the Igor Pro epoch (1/1/1904) in UTC (or local time zone depending on localTimeZone)

  • numFracSecondsDigits – [optional, defaults to zero] Number of sub-second digits

  • localTimeZone – [optional, defaults to false] Use the local time zone instead of UTC

variable ParseUnit(string unitWithPrefix, string *prefix, variable *numPrefix, string *unit)

Parse a simple unit with prefix into its prefix and unit.

Note: The currently allowed units are the SI base units [1] and other common derived units. And in accordance to SI definitions, “kg” is a base unit. “Simple” unit means means one unit with prefix, not e.g. “km/s”.

Name

Symbol

Numerical value

yotta

Y

1e24

zetta

Z

1e21

exa

E

1e18

peta

P

1e15

tera

T

1e12

giga

G

1e9

mega

M

1e6

kilo

k

1e3

hecto

h

1e2

deca

da

1e1

deci

d

1e-1

centi

c

1e-2

milli

m

1e-3

micro

mu

1e-6

nano

n

1e-9

pico

p

1e-12

femto

f

1e-15

atto

a

1e-18

zepto

z

1e-21

yocto

y

1e-24

[1]: 8th edition of the SI Brochure (2014), http://www.bipm.org/en/publications/si-brochure

Parameters:

  • unitWithPrefix – [in] string to parse, examples are “ms” or “kHz”

  • prefix – [out] symbol of decimal multipler of the unit, see below or [1] chapter 3 for the full list

  • numPrefix – [out] numerical value of the decimal multiplier

  • unit – [out] unit

variable GetDecimalMultiplierValue(string prefix)

Return the numerical value of a SI decimal multiplier.

See also

ParseUnit

variable IsTextWave(wave wv)

Return 1 if the wave is a text wave, zero otherwise.

variable IsNumericWave(wave wv)

Return 1 if the wave is a numeric wave, zero otherwise.

string RemovePrefixFromListItem(string prefix, string list, string listSep = defaultValue)

Remove a string prefix from each list item and return the new list.

wave MakeWaveFree(wave wv)

Turn a persistent wave into a free wave.

string UniqueWaveName(dfref dfr, string baseName)

Returns a wave name not used in the given datafolder.

Basically a datafolder aware version of UniqueName for datafolders

Parameters:

  • dfr – datafolder reference where the new datafolder should be created

  • baseName – first part of the wave name, might be shorted due to Igor Pro limitations

variable DataFolderExistsDFR(dfref dfr)

Checks if the datafolder referenced by dfr exists.

Unlike DataFolderExists() a dfref pointing to an empty (“”) dataFolder is considered non-existing here.

Returns:

one if dfr is valid and references an existing or free datafolder, zero otherwise Taken from http://www.igorexchange.com/node/2055

string GetBaseName(string filePathWithSuffix, string sep = defaultValue)

Return the base name of the file.

Given path/file.suffix this gives file.

Parameters:

  • filePathWithSuffix – full path

  • sep – [optional, defaults to “:”] character separating the path components

string GetFileSuffix(string filePathWithSuffix, string sep = defaultValue)

Return the file extension (suffix)

Given path/file.suffix this gives suffix.

Parameters:

  • filePathWithSuffix – full path

  • sep – [optional, defaults to “:”] character separating the path components

string GetFolder(string filePathWithSuffix, string sep = defaultValue)

Return the folder of the file.

Given /path/file.suffix this gives path/.

Parameters:

  • filePathWithSuffix – full path

  • sep – [optional, defaults to “:”] character separating the path components

string GetFile(string filePathWithSuffix, string sep = defaultValue)

Return the filename with extension.

Given path/file.suffix this gives file.suffix.

Parameters:

  • filePathWithSuffix – full path

  • sep – [optional, defaults to “:”] character separating the path components

variable ParseISO8601TimeStamp(string timestamp)

Parse a ISO8601 timestamp, e.g. created by GetISO8601TimeStamp(), and returns the number of seconds, including fractional parts, since Igor Pro epoch (1/1/1904) in UTC time zone.

Accepts also the following specialities:

  • no UTC timezone specifier (UTC timezone is still used)

  • /T between date and time

  • fractional seconds

  • ,/. as decimal separator

string TextWaveToList(WaveText txtWave, string sep)

Convert a text wave to string list.

string ResolveAlias(string path, string pathName = defaultValue)

Recursively resolve shortcuts to files/directories.

Returns:

full path or an empty string if the file does not exist or the shortcut points to a non existing file/folder

variable FileExists(string filepath)

Check wether the given path points to an existing file.

Resolves shortcuts and symlinks recursively.

variable FolderExists(string folderpath)

Check wether the given path points to an existing folder.

string AddPrefixToEachListItem(string prefix, string list)

Add a string prefix to each list item and return the new list.

variable NewRandomSeed()

Initializes the random number generator with a new seed between (0,1] The time base is assumed to be at least 0.1 microsecond precise, so a new seed is available every 0.1 microsecond.

Usage example for the case that one needs n non reproducible random numbers. Whenever the following code block is executed a new seed is set, resulting in a different series of numbers

Make/D/N=(n) newRandoms
NewRandomSeed() // Initialize random number series with a new seed
newRandoms[] = GetReproducibleRandom() // Get n randoms from the new series

variable GetReproducibleRandom()

Return a random value in the range (0,1] which can be used as a seed for SetRandomSeed

Return a reproducible random number depending on the RNG seed.

string GenerateRFC4122UUID()

Generate a version 4 UUID according to https://tools.ietf.org/html/rfc4122. 

///
///     4.4.  Algorithms for Creating a UUID from Truly Random or
///           Pseudo-Random Numbers
///
///        The version 4 UUID is meant for generating UUIDs from truly-random or
///        pseudo-random numbers.
///
///        The algorithm is as follows:
///
///        o  Set the two most significant bits (bits 6 and 7) of the
///           clock_seq_hi_and_reserved to zero and one, respectively.
///
///        o  Set the four most significant bits (bits 12 through 15) of the
///           time_hi_and_version field to the 4-bit version number from
///           Section 4.1.3.
///
///        o  Set all the other bits to randomly (or pseudo-randomly) chosen
///           values.
///
///     See Section 4.5 for a discussion on random numbers.
///
///     [...]
///
///      In the absence of explicit application or presentation protocol
///      specification to the contrary, a UUID is encoded as a 128-bit object,
///      as follows:
///
///      The fields are encoded as 16 octets, with the sizes and order of the
///      fields defined above, and with each field encoded with the Most
///      Significant Byte first (known as network byte order).  Note that the
///      field names, particularly for multiplexed fields, follow historical
///      practice.
///
///      0                   1                   2                   3
///       0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
///      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
///      |                          time_low                             |
///      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
///      |       time_mid                |         time_hi_and_version   |
///      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
///      |clk_seq_hi_res |  clk_seq_low  |         node (0-1)            |
///      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
///      |                         node (2-5)                            |
///      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
///
///     [...]
///
///     4.1.3.  Version
///
///        The version number is in the most significant 4 bits of the time
///        stamp (bits 4 through 7 of the time_hi_and_version field).
///
///        The following table lists the currently-defined versions for this
///        UUID variant.
///
///        Msb0  Msb1  Msb2  Msb3   Version  Description
///
///         0     0     0     1        1     The time-based version
///                                          specified in this document.
///
///         0     0     1     0        2     DCE Security version, with
///                                          embedded POSIX UIDs.
///
///         0     0     1     1        3     The name-based version
///                                          specified in this document
///                                          that uses MD5 hashing.
///
///         0     1     0     0        4     The randomly or pseudo-
///                                          randomly generated version
///                                          specified in this document.
///
///         0     1     0     1        5     The name-based version
///                                          specified in this document
///                                          that uses SHA-1 hashing.
///
///        The version is more accurately a sub-type; again, we retain the term
///        for compatibility.
///
///

See also https://www.rfc-editor.org/errata/eid3546 and https://www.rfc-editor.org/errata/eid1957 for some clarifications.

variable HexToNumber(string ch)

Convert a hexadecimal character into a number.

string NumberToHex(variable var)

Convert a number into hexadecimal.

wave HexToBinary(string str)

Convert a string in hex format to an unsigned binary wave.

This function works on a byte level so it does not care about endianess.

string num2strHighPrec(variable val, variable precision = defaultValue)

Converts a number to a string with specified precision (digits after decimal dot). This function is an extension for the regular num2str that is limited to 5 digits. Input numbers are rounded using the “round-half-to-even” rule to the given precision. The default precision is 5. If val is complex only the real part is converted to a string.

Parameters:

  • val – [in] number that should be converted to a string

  • precision – [in] [optional, default 5] number of precision digits after the decimal dot using “round-half-to-even” rounding rule. Precision must be in the range 0 to 15.

Returns:

string with textual number representation

variable ClearRTError()

Helper function for try/catch with AbortOnRTE.

Not clearing the RTE before calling AbortOnRTE will always trigger the RTE no matter what you do in that line.

Usage: 

try
   ClearRTError()
   myFunc(); AbortOnRTE
catch
  err = GetRTError(1)
endtry

string NormalizeToEOL(string str, string eol)

Normalize the line endings in the given string to either classic Mac OS/Igor Pro EOLs (\r) or Unix EOLs (\n)

string GetStackTrace(string prefix = defaultValue)

Return a nicely formatted multiline stacktrace.

string GetExperimentName()
string GetExperimentFileType()

Return the experiment file type.

string GetIgorProVersion()

Return the Igor Pro version string.

string GetWindowsPath(string path)

Return the path converted to a windows style path.

variable SetEpochsDimensionLabels(wave wv)
wave GetUniqueEntries(wave wv, variable caseSensitive = defaultValue)

Returns an unsorted free wave with all unique entries from wv neglecting NaN/Inf.

uses built-in igor function FindDuplicates. Entries are deleted from left to right.

string GetUniqueTextEntriesFromList(string list, string sep = defaultValue, variable caseSensitive = defaultValue)

Convenience wrapper around GetUniqueTextEntries() for string lists.

static wave GetUniqueTextEntries(WaveText wv, variable caseSensitive = defaultValue)

Search and Remove Duplicates from Text Wave wv.

Duplicates are removed from left to right

Parameters:

  • wv – text wave reference

  • caseSensitive – [optional] Indicates whether comparison should be case sensitive. defaults to True

Returns:

free wave with unique entries

variable SetNumberInWaveNote(wave wv, string key, variable val, string format = defaultValue)

Updates the numeric value of key found in the wave note to val

The expected wave note format is: key1:val1;key2:val2;

Parameters:

  • wv – wave

  • key – key of the Key/Value pair

  • val – value of the Key/Value pair

  • format – [optional] printf compatible format string to set the conversion to string for val

variable GetNumberFromWaveNote(wave wv, string key)

Returns the numeric value of key found in the wave note, returns NaN if it could not be found.

The expected wave note format is: key1:val1;key2:val2;

struct Uuid