errpref

package module
v1.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 4, 2021 License: MIT Imports: 3 Imported by: 6

README

errpref - Adding error prefix, function execution chains and error context to Error Messages In Go

The errpref software package contains two GoLang types designed to attach error prefix text, function execution chain lists and error context strings to error messages.

The errpref software package was written in the Go programming language, a.k.a. Golang.

errpref supports Go Modules.

The current version of errpref is Version 1.7.0 which includes two important upgrades:

For more details, see the Release Notes.

Table of Contents

The Problem

As my Go programs, types and methods have grown in sophistication and complexity, the need for improved error tracking, detailed error messages, and a bread crumb trail of code execution has become more important. The terms 'Function Chains' or 'Method Chains', as used here, describes a list of the functions called prior to encountering a particular error. Adding function chain documentation to returned error messages makes error tracking and management a much easier proposition.

Basically, when I see an error message, especially during the development phase, the first question that comes to mind is, How the Hell did I get here? Answering that question quickly, and with certainty, usually requires a list of functions ordered by their execution sequence. Adding that information to error messages is the focus of this project.

The Solution

The errpref or Error Prefix project is intended to provide better function or method documentation in error messages returned by Go functions. Two types have been defined for this purpose: ErrPref and ErrPrefixDto. Both of these types are designed to receive function chain information, format it and return the formatted strings for inclusion in error messages.

From a usage standpoint, ErrPref and ErrPrefixDto collect information in string form at each method or function in the execution chain. If an error occurs, the user is responsible for extracting the collected information from ErrPref or ErrPrefixDto and integrating that information into the returned error message. While these types are designed to collect error prefix and error context information, they can in fact be used to collect any required informational or error related messaging in string format. This could be error numbers, execution or debugging information or virtually any text specified by the developer. In addition, despite the name 'error prefix', there is no requirement that this information be attached to the beginning of an error message. As a practical matter, the information could be injected as a string anywhere in the returned error message or informational message display.

Wait a Minute - Let's Think About This

So, if you only take a quick look at the errpref package you might be tempted to say, "Whoopee - all you've done is concatenate a series of strings!"

That's what I thought, at first. However, there is the problem of delimiting error prefixes and error context information plus the problem of determining how much information to show on each line, plus the problem of receiving error prefix information from external sources in various formats - and the list goes on.

With types ErrPref and ErrPrefixDto, the user may configure the line length which will determine whether a new line character (\n) or in-line delimiter string ([SPACE]-[SPACE]) is used to separate error prefix information.

ErrPrefixDto utilizes a series of interfaces to receive and exchange data with external sources. In addition, ErrPrefixDto implements a variable or custom string delimiter feature which allows the user to process error prefix strings received from external sources in a variety of formats.

To summarize: If you are serious about error management and tracking, the errpref package might be worth a second look.

What errpref Does and Doesn't Do

The errpref package generates text strings which can be populated with error prefix and error context information. It does NOT create error messages. Error messages are still created by the user with the standard tools provided by the Go Programming Language.

errpref is used to generate the error prefix, function chain and error context information. After that, it is up to the user to add this information to the error message.

	if inComingFormatterCurrency == nil {
		err = fmt.Errorf("%v\n"+
			"Error: Input parameter 'inComingFormatterCurrency' is"+
			" a 'nil' pointer!\n",
			errPrefixDto.String())
		return err
	}

In the example above, errPrefixDto is an instance of the errpref type ErrPrefixDto previously configured with a series of method names documenting the execution path which led to this point in the code. As the example shows, the user is still responsible for configuring the error message in its entirety.

While the errpref package was specifically designed to document function or method chains of execution, the example above shows that, as a practical matter, the user is free to position this text anywhere in the error message. Also, this text is not reserved exclusively for error messages. It could be used in informational messages or any other type of text display.

The typical error message decorated with error prefix and context information will typically look something like this:

main()-mainTest004()
TestFuncsDto.TestAlphaDto001()
 :  A->B
TestFuncDtoAlpha01.Tx1DoSomething()
testFuncDtoAlpha02.tx2DoSomethingElse()
testFuncDtoAlpha03.tx3DoAnything()
testFuncDtoAlpha04.tx4DoNothing()
 :  A/B==4
testFuncDtoAlpha05.tx5DoSomethingBig()
 :  A->B
testFuncDtoAlpha06.tx6TryGivingUp()
 :  A/B = C B==0
Example Error: An Error Ocurred! Something bad.
Like Divide by Zero

This example error message was taken from the errpref example application, errorPrefixExamples.

Definition of Terms

For our purposes, error prefix information consists of two elements:

  1. One or more function or method names listed in sequence of code execution.
  2. An optional error context string associated with a specific function or method name.
Error Prefix

Error Prefix text is designed to be configured at the beginning of error messages and is most often used to document the thread of code execution by listing the calling sequence for a specific list of functions and/or methods. As a previously stated, there is no hard and fast requirement that it be attached to the beginning of an error message. The user is free to inject this text string where ever it is most useful.

Error Context

Error Context strings are designed to provide additional information about the function or method identified by the associated Error Prefix text. Typical context information might include variable names, variable values, error numbers or details about function execution.

An Error Context cannot be created as a stand-alone object. It is always paired with an Error Prefix. Error Context strings are optional, but when created they are always associated with an Error Prefix string.

Getting Started

Two Types To Choose From

Currently, the errpref package provides two types offering error prefix formatting services: ErrPrefixDto and ErrPref. Type ErrPref offers basic error prefix formatting while type ErrPrefixDto provides a much wider range of formatting and data transmission capabilities.

The Error Prefix Data Transfer Object, ErrPrefixDto, offers the same services as type, ErrPref, but is packaged in a different architecture. While ErrPref methods receive a string and instantly return a formatted string, ErrPrefixDto encapsulates error prefix information in an internal array of Error Prefix Information objects (ErrorPrefixInfo). Strings are only created when the type's String() or StrMaxLineLen() methods are called. Instances of ErrPrefixDto are designed to be passed as input parameters to subsidiary methods. The act of passing ErrPrefixDto objects to successive functions in the execution sequence effectively builds documentation of the execution function chain.

The String() method has a value receiver. Virtually all other ErrPrefixDto methods have pointer receivers.

Public Facing Methods

A public method may receive error prefix information in a variety of formats from sources both internal and external to your application. To date, the best use scenario for a Public Facing Function or Method follows this pattern:

func (numStrBasic *NumStrBasic) GetCountryFormatters(
  fmtCollection *FormatterCollection,
  countryCulture CountryCultureId,
  errorPrefix interface{}) error {

  var ePrefix *ErrPrefixDto
  var err error

  ePrefix,
    err = ErrPrefixDto{}.NewIEmpty(
    errorPrefix,
    "NumStrBasic.GetCountryFormatters()",
    "")

  if err != nil {
    return err
  }

  return numStrBasicQuark{}.ptr().
    getCountryFormatters(
      fmtCollection,
      countryCulture,
      ePrefix)
}

By calling ErrPrefixDto{}.NewIEmpty() with an empty interface, functions can pass error prefix information in any of 10-different formats:

  1. nil - A nil value is valid and generates an empty collection of error prefix and error context information.
  2. Stringer - The Stringer interface from the 'fmt' package. This interface has only one method:
    	type Stringer interface {
    		String() string
    	}
  1. string - A string containing error prefix information. For maximum effectiveness, this should be delimited with the standard String Delimiters.
  2. []string - A one-dimensional slice of strings containing error prefix information. Typically, the one-dimensional slice contains only function or method names.
  3. [][2]string - A two-dimensional slice of strings containing error prefix and error context information. slice[x][0] holds function or method names. slice[x][1] holds associated error context information.
  4. strings.Builder - An instance of strings.Builder. Error prefix information extracted from strings.Builder will be imported into the new returned instance of *ErrPrefixDto.
  5. *strings.Builder - A pointer to an instance of strings.Builder. Extracted error prefix information will be imported into the new returned instance of *ErrPrefixDto.
  6. ErrPrefixDto - An instance of ErrPrefixDto. The ErrorPrefixInfo collection extracted from this object will be copied to the new returned instance of *ErrPrefixDto.
  7. *ErrPrefixDto - A pointer to an instance of ErrPrefixDto. The ErrorPrefixInfo collection extracted from this object will be copied to the new returned instance of *ErrPrefixDto.
  8. IBasicErrorPrefix - An interface to a method generating a two-dimensional slice of strings containing error prefix and error context information.
             type IBasicErrorPrefix interface {
               GetEPrefStrings() [][2]string
             }

The Method Signature for ErrPrefixDto{}.NewIEmpty() is shown below:

func (ePrefDto ErrPrefixDto) NewIEmpty(
	iEPref interface{},
	newErrPrefix string,
	newErrContext string) (
	*ErrPrefixDto,
	error)

This pattern allows for use of the nil value. This means that parameter iEPref will accept a nil value. If no error prefix information is present or required, just pass a nil value for the iEPref parameter.

Finally, notice how the currently executing method name (NumStrBasic.GetCountryFormatters()) is added to the error prefix method chain:

	ePrefix,
		err = ErrPrefixDto{}.NewIEmpty(
		errorPrefix,
		"NumStrBasic.GetCountryFormatters()",
		"")

The final empty string parameter is optional and could be used to add error context information.

Internal or Private Methods

In the Public Facing Methods example, above, method GetCountryFormatters() makes a call to the internal or private method, getCountryFormatters(). Calls like this one to a supporting or subsidiary method usually pass a pointer to an instance of ErrPrefixDto. To date, the best use scenario for calls to subsidiary methods follows this pattern:


func (nStrBasicQuark numStrBasicQuark) getCountryFormatters(
	fmtCollection *FormatterCollection,
	countryCulture CountryCultureId,
	errPrefix *ErrPrefixDto) (
	err error) {
	
    ePrefix,
	err := ErrPrefixDto{}.NewFromErrPrefDto(
		errPrefix,
		"numStrBasicQuark.getCountryFormatters()",
		"")

	if err != nil {
		return err
	}

	if fmtCollection == nil {
		err = fmt.Errorf("%v\n"+
			"Error: Input parameter 'fmtCollection' is "+
			"a 'nil' pointer!\n",
			ePrefix.String())

		return err
	}

    ...

Notice how the function name is added to the error prefix chain:

	ePrefix,
	err := ErrPrefixDto{}.NewFromErrPrefDto(
		errPrefix,
		"numStrBasicQuark.getCountryFormatters()",
		"")

This is the method signature for NewFromErrPrefDto():

func (ePrefDto ErrPrefixDto) NewFromErrPrefDto(
	dto *ErrPrefixDto,
	newErrPrefix string,
	newErrContext string) (
	newErrPrefDto *ErrPrefixDto,
	err error)

This method makes provision for the inclusion of an optional error context string.

Also, notice that this pattern allows for use of the nil value for parameter, dto. If no error prefix information is present or required, just pass a nil parameter value.

This pattern provides a separate function chain string for each method. This architecture allows for multiple calls from parent methods without adding unnecessary and irrelevant text to the function chain. If an error occurs, only the relevant error prefix and error context information will be returned in the formatted error message.

Error Context Example

Recall that Error Context strings are designed to provide additional information about the function or method identified by the associated Error Prefix text. Typical context information might include variable names, variable values and additional details on function execution.

In this example, a function chain is built by calls to multiple levels of the code hierarchy. The final call to method Tx3.DoSomething() triggers an error thereby returning the names of all methods in the call chain plus error context information associated with those methods.

func(tx1 *Tx1) Something() {

  ePrefDto := ErrPrefixDto{}.New()

  ePrefDto.SetEPref("Tx1.Something()")

  tx2 := Tx2{}

  err := tx2.SomethingElse(&ePrefDto)

  if err !=nil {
    fmt.Printf("%v\n",
    err.Error())
    return
  }

}

func(tx2 *Tx2) SomethingElse(ePrefDto *ErrPrefixDto) error {

	ePrefix,
		err := ErrPrefixDto{}.NewFromErrPrefDto(
		ePrefDto,
		"Tx2.SomethingElse()",
		"")

	if err != nil {
		return err
	}

  	tx3 := Tx3{}

  	err := tx3.DoSomething(ePrefix)

  	if err !=nil {
    	return err
  	}
}

func(tx3 *Tx3) DoSomething(ePrefDto *ErrPrefixDto) error {

   // Add error prefix and error context
    // information.
	ePrefix,
		err := ErrPrefixDto{}.NewFromErrPrefDto(
		ePrefDto,
		"Tx3.DoSomething()",
		"A=B/C C= 0")

	if err != nil {
		return err
	}

    .... bad code ....

    if isDivideByZero {
      return fmt.Errorf("%v\n" +
      "I divided by zero and got this error.\n",
      ePrefix.String())
    }
}

When this error is returned up the function chain and finally printed out, the text will look like this:

 Tx1.Something() - Tx2.SomethingElse()
 Tx3.DoSomething() : A=B/C C= 0
 I divided by zero and got this error.
Customizing Input and Output String Delimiters

Unlike type ErrPref, ErrPrefixDto allows users to configure the string delimiters used to parse input strings containing error prefix information received from external sources. This facilitates the exchange of error prefix information received from outside sources by ensuring that error prefix string components are properly separated and identified during the parsing operation. In addition, users may also specify the string delimiters used to combine and join error prefix components for generation and formatting of output text incorporated in error messages.

Internally, ErrPrefixDto maintains two types of string delimiters, Input String Delimiters and Output String Delimiters.

Input String Delimiters are used to parse raw string values containing error prefix and error context information received as input parameters from external sources. Methods performing this type of operation include:

ErrPrefixDto.NewEPrefOld
ErrPrefixDto.NewFromStrings()
ErrPrefixDto.NewFromStrings()
ErrPrefixDto.NewIEmptyWithDelimiters()
ErrPrefixDto.SetEPrefOld()
ErrPrefixDto.XEPrefOld()
ErrPrefixDto.ZEPrefOld()

Output String Delimiters are used by ErrPrefixDto instances to join or concatenate individual error prefix and error context components to form presentation text for output and use in preparation of error message strings. Methods performing this type of operation are:

ErrPrefixDto.String()
ErrPrefixDto.StrMaxLineLen()

Initially, both the Input and Output String Delimiters for any given ErrPrefixDto instance are set to the system default values. This means that if the Input and Output String Delimiters were not directly configured by the user, the system default string delimiters are applied.

The system defaults for both Input and Output String Delimiters are listed as follows:

 New Line Error Prefix Delimiter  = "\n"
 In-Line Error Prefix Delimiter   = " - "
 New Line Error Context Delimiter = "\n :  "
 In-Line Error Context Delimiter  = " : "

if required, the Input and Output String Delimiters can always be reset to system default values by calling method:

func (ePrefDto *ErrPrefixDto) SetStrDelimitersToDefault()

However, users do have the option of setting custom Input and Output String Delimiters using methods:

func (ePrefDto *ErrPrefixDto) SetInputStringDelimiters(
	inputStrDelimiters ErrPrefixDelimiters,
	ePrefix string) error

func (ePrefDto *ErrPrefixDto) SetOutputStringDelimiters(
	outputStrDelimiters ErrPrefixDelimiters,
	ePrefix string) error

In terms of output text, a variety of interesting and creative display effects can be achieved through manipulating the Output String Delimiters. However, when configuring Output String Delimiters it may be necessary to coordinate the Maximum Text Line Length which is initially set to a default of 40-characters. Configuring Output String Delimiters should be coupled with managing the Maximum Text Line Length discussed below.

The current settings for String Delimiters can be monitored using methods:

 ErrPrefixDto.GetStrDelimiters()
 ErrPrefixDto.GetInputStringDelimiters()
 ErrPrefixDto.GetOutputStringDelimiters()
Maximum Text Line Length

Users have the option of setting the Maximum Text Line Length for error prefix strings. The default Maximum Text Line Length is 40-characters. The Minimum Text Line Length is 10-characters.

The following error prefix text display demonstrates the default 40-character maximum line length.

main()-mainTest004()
TestFuncsDto.TestAlphaDto001()
 :  A->B
TestFuncDtoAlpha01.Tx1DoSomething()
testFuncDtoAlpha02.tx2DoSomethingElse()
testFuncDtoAlpha03.tx3DoAnything()
testFuncDtoAlpha04.tx4DoNothing()
 :  A/B==4
testFuncDtoAlpha05.tx5DoSomethingBig()
 :  A->B
testFuncDtoAlpha06.tx6TryGivingUp()
 :  A/B = C B==0
Example Error: An Err

The next example shows the same error prefix information displayed with a custom Maximum Text Line Length of 70-characters.

main()-mainTest005() - TestFuncsDto.TestAlphaDto002()
TestFuncDtoAlpha01.Tx1DoSomething()
testFuncDtoAlpha02.tx2DoSomethingElse()
testFuncDtoAlpha03.tx3DoAnything()
testFuncDtoAlpha04.tx4DoNothing() : A/B==4
testFuncDtoAlpha05.tx5DoSomethingBig() : A->B
testFuncDtoAlpha06.tx6TryGivingUp() : A/B = C B==0
Example Error: An Error Ocurred! Something bad.
Like Divide by Zero!

The Maximum Text Line Length is monitored and controlled using methods:

  • ErrPrefixDto.SetMaxTextLineLen()
  • ErrPrefixDto.GetMaxTextLineLen()
  • ErrPrefixDto.SetMaxTextLineLenToDefault()

Be advised that the minimum text line Length is 10-characters. Any attempt to set the Maximum Text Line Length to a value less than 10-characters will result in reinstatement of the default Maximum Text Line Length.

This example error messages shown above were taken from the errpref example application, errorPrefixExamples.

Left Margin Feature

The default left margin length for text returned by the method ErrPrefixDto.String() is zero (0). In other words, by default, there is no left margin.

Example error prefix information text display with left margin length of zero:

Tx1.Something() - Tx2.SomethingElse()
Tx3.DoSomething() - Tx4() - Tx5()
Tx6.DoSomethingElse()
Tx7.TrySomethingNew()
 :  something->newSomething
Tx8.TryAnyCombination()
Tx9.TryAHammer() : x->y - Tx10.X()
Tx11.TryAnything() - Tx12.TryASalad()
Tx13.SomeFabulousAndComplexStuff()
Tx14.MoreAwesomeGoodness()
 :  A=7 B=8 C=9

The following ErrPrefixDto methods allow the user to control both the left margin length, and the character used to populate the left margin:

  1. ErrPrefixDto.SetLeftMarginLength()
  2. ErrPrefixDto.SetLeftMarginChar()
  3. ErrPrefixDto.GetLeftMarginLength()
  4. ErrPrefixDto.GetLeftMarginChar()

In the next example, the left margin length is set to three (3), and the left margin character is set to the empty space character (' ') or ASCII 0x20:

   Tx1.Something() - Tx2.SomethingElse()
   Tx3.DoSomething() - Tx4() - Tx5()
   Tx6.DoSomethingElse()
   Tx7.TrySomethingNew()
    :  something->newSomething
   Tx8.TryAnyCombination()
   Tx9.TryAHammer() : x->y - Tx10.X()
   Tx11.TryAnything() - Tx12.TryASalad()
   Tx13.SomeFabulousAndComplexStuff()
   Tx14.MoreAwesomeGoodness()
    :  A=7 B=8 C=9

In the final example, the left margin length is set to three (3), and the left margin character is set to the asterisk character ('*'):

***Tx1.Something() - Tx2.SomethingElse()
***Tx3.DoSomething() - Tx4() - Tx5()
***Tx6.DoSomethingElse()
***Tx7.TrySomethingNew()
*** :  something->newSomething
***Tx8.TryAnyCombination()
***Tx9.TryAHammer() : x->y - Tx10.X()
***Tx11.TryAnything() - Tx12.TryASalad()
***Tx13.SomeFabulousAndComplexStuff()
***Tx14.MoreAwesomeGoodness()
*** :  A=7 B=8 C=9
Leading And Trailing Text Strings

Users have the option of adding leading or trailing text strings to the error prefix display. Leading Text Strings will be added to the beginning of the text display while Trailing Text Strings will be added to the end of the text display.

Leading and Trailing Text Strings may be comprised of any valid string of characters including new lines ('\n'), tabs ('\t') and line separators.

The addition of Leading and Trailing Text Strings is controlled through the following methods:

  • ErrPrefixDto.SetLeadingTextStr()
  • ErrPrefixDto.SetTrailingTextStr()
  • ErrPrefixDto.GetLeadingTextStr()
  • ErrPrefixDto.GetTrailingTextStr()
  • ErrPrefixDto.ClearLeadingTextStr()
  • ErrPrefixDto.ClearTrailingTextStr()

Consider the following example:

	ePDto := errpref.ErrPrefixDto{}.New()

	maxLineLen := 50

	ePDto.SetMaxTextLineLen(maxLineLen)

	var twoDSlice [][2]string

	twoDSlice = make([][2]string, 14)

	twoDSlice[0][0] = "Tx1.Something()"
	twoDSlice[0][1] = ""

	twoDSlice[1][0] = "Tx2.SomethingElse()"
	twoDSlice[1][1] = ""

	twoDSlice[2][0] = "Tx3.DoSomething()"
	twoDSlice[2][1] = ""

	twoDSlice[3][0] = "Tx4()"
	twoDSlice[3][1] = ""

	twoDSlice[4][0] = "Tx5()"
	twoDSlice[4][1] = ""

	twoDSlice[5][0] = "Tx6.DoSomethingElse()"
	twoDSlice[5][1] = ""

	twoDSlice[6][0] = "Tx7.TrySomethingNew()"
	twoDSlice[6][1] = "something->newSomething"

	twoDSlice[7][0] = "Tx8.TryAnyCombination()"
	twoDSlice[7][1] = ""

	twoDSlice[8][0] = "Tx9.TryAHammer()"
	twoDSlice[8][1] = "x->y"

	twoDSlice[9][0] = "Tx10.X()"
	twoDSlice[9][1] = ""

	twoDSlice[10][0] = "Tx11.TryAnything()"
	twoDSlice[10][1] = ""

	twoDSlice[11][0] = "Tx12.TryASalad()"
	twoDSlice[11][1] = ""

	twoDSlice[12][0] = "Tx13.SomeFabulousAndComplexStuff()"
	twoDSlice[12][1] = ""

	twoDSlice[13][0] = "Tx14.MoreAwesomeGoodness()"
	twoDSlice[13][1] = "A=7 B=8 C=9"

	ePDto.SetEPrefStrings(twoDSlice)

	leadingText := "\n" +
		strings.Repeat("-", maxLineLen)

	trailingText := strings.Repeat("-", maxLineLen) +
		"\n"

	ePDto.SetLeadingTextStr(leadingText)
	ePDto.SetTrailingTextStr(trailingText)
	ePDto.SetIsLastLineTermWithNewLine(true)

	outputStr := fmt.Sprintf("%v"+
		"Error: Divide by Zero!",
		ePDto.String())

	fmt.Printf(outputStr)

The the example above the final outputStr will be formatted as:

 --------------------------------------------------
 Tx1.Something() - Tx2.SomethingElse()
 Tx3.DoSomething() - Tx4() - Tx5()
 Tx6.DoSomethingElse()
 Tx7.TrySomethingNew() : something->newSomething
 Tx8.TryAnyCombination() - Tx9.TryAHammer() : x->y
 Tx10.X() - Tx11.TryAnything() - Tx12.TryASalad()
 Tx13.SomeFabulousAndComplexStuff()
 Tx14.MoreAwesomeGoodness() : A=7 B=8 C=9
 --------------------------------------------------
 Error: Divide by Zero!
Text Display On/Off Switch

ErrPrefixDto implements a feature which allows the user to turn off the generation of output strings containing error prefix information. The typical means of injecting output text into an error message follows this example:

    if isDivideByZero {
      return fmt.Errorf("%v\n" +
      "I divided by zero and got this error.\n",
      ePrefDto.String())
    }

In this example. the call to ePrefDto.String() will generate a string containing error prefix information which is then inserted into the returned error message. However, ErrPrefixDto now provides a mechanism for "Turning Off" this error prefix string generation. Users control this "On/Off" switch through calls to method:

func (ePrefDto *ErrPrefixDto) SetTurnOffTextDisplay(
	turnOffTextDisplay bool)

Calling this method with parameter turnOffTextDisplay set to true will ensure the future calls to ErrPrefixDto.String() and ErrPrefixDto.StrMaxLineLen() will return an empty string. Assuming Text Display was turned-off, the call to ePrefDto.String() in the "Divide By Zero" example above, would return an empty string. The net result is that no error prefix information would be injected in to the error message in this example.

Is Last Text Line Terminated With New Line

By default, the last line of error prefix strings returned by the methods ErrPrefixDto.String() and ErrPrefixDto.StrMaxLineLen() ARE NOT terminated with a new line character ('\n'). Consider the following example:

    if isDivideByZero {
      return fmt.Errorf("%v\n" + // <------ User manually inserted new character after error prefix string.
      "I divided by zero and got this error.\n",
      ePrefDto.String())
    }

Here, the user is manually inserting a new line character after the error prefix string because the error prefix does NOT include a new line character. Therefore, when this error is returned up the function chain and finally printed out, the text will look like this:

 Tx1.Something() - Tx2.SomethingElse()
 Tx3.DoSomething() : A=B/C C== 0.0    <------ User added a new line character
 I divided by zero and got this error.

If the last line of error prefix strings should be automatically terminated with a new line character ('\n'), call the following method:

func (ePrefDto *ErrPrefixDto) SetIsLastLineTermWithNewLine(
	isLastLineTerminatedWithNewLine bool)

Setting input parameter isLastLineTerminatedWithNewLine to true will effectively add a new line character ('\n') to all error prefix strings returned by methods:

func (ePrefDto ErrPrefixDto) String() string

func (ePrefDto *ErrPrefixDto) StrMaxLineLen(
	maxLineLen int) string

In the 'Divide by Zero' example, the user no longer needs to manually add the new line character:

 if isDivideByZero {
      return fmt.Errorf("%v" + <------ // User did NOT insert new character after error prefix string.
      "I divided by zero and got this error.\n",
      ePrefDto.String())
    }

When this error is returned up the function chain and finally printed out, the text will look like this:

 Tx1.Something() - Tx2.SomethingElse()
 Tx3.DoSomething() : A=B/C C== 0.0 <--- New line character automatically added to end of error prefix sring.
 I divided by zero and got this error.
ErrPref - Quick And Simple Solution

Type ErrPref is designed to format error prefix text strings for use in error messages. ErrPref is simple, lightweight, easy to use and seems to work in a variety of situations. The concept is straight forward, "Put raw text strings in - Get formatted error prefix information out".

The ErrPref methods do not use pointer receivers. All receivers are value receivers.

The ErrPref type does not store error prefix information like the ErrPrefixDto type. Again, the concept is, "Put raw strings in - Get formatted error prefix strings out".

Example Usage Summary

ErrPref passes error prefix information by string. An example calling sequence is shown as follows:


func(tx1 *Tx1) Something() {

 tx2 := Tx2{}

 err := Tx2.SomethingElse("Tx1.Something()")

 if err !=nil {
   fmt.Printf("%v\n",
   err.Error())
   return
 }

}

func(tx2 *Tx2) SomethingElse(errPrefix string) error {

  // errorPrefix now equals "Tx1.Something()"
  errorPrefix := ErrPref{}.EPrefOld(errPrefix)

  // errorPrefix now equals
  // "Tx1.Something() - Tx2.SomethingElse()"
  errorPrefix = ErrPref{}.EPref(
    errorPrefix,
    "Tx2.SomethingElse()")

  tx3 := Tx3{}

  err := Tx3.DoSomething(errorPrefix)

  if err !=nil {
   return err
  }
}

func(tx3 *Tx3) DoSomething(errorPrefix string) error {

    // Adding Error Context
    errorPrefix = ErrPref{}.EPrefCtx(
                   "Tx3.DoSomething()",
                   "A=B/C C== 0.0")

    .... bad code ....

    if isDivideByZero {
      return fmt.Errorf("%v\n" +
      "I divided by zero and got this error.\n",
      errorPrefix)
    }
}

When this error is returned up the function chain and finally printed out, the text will look like this:

 Tx1.Something() - Tx2.SomethingElse()
 Tx3.DoSomething() : A=B/C C== 0.0
 I divided by zero and got this error.
String Formatting Conventions

When using the methods provided by type ErrPref, incoming error prefix strings are parsed for function names, method names and error context information based on specific string delimiters. For type ErrPref, these string delimiters are standardized, fixed and not subject to customization by the user. The system default input and output string delimiters are defined as follows:

Error Prefix Delimiters

Error Prefix Elements are delimited by one of two delimiters:

  • New Line Delimiter = "\n" Delimits function/method names on a single line.
  • In-Line Delimiter = " - " ([SPACE]-[SPACE]) Delimits multiple function/method names on the same line.
Error Context Delimiters

Associated Error Context Sub-Elements likewise have two delimiters:

  • New Line Delimiter String = "\n[SPACE]:[SPACE][SPACE]" Delimits error context information on a single line.
  • In-Line Delimiter String = "[SPACE]:[SPACE]" Delimits error context information displayed with function/method name on same line.

If variable or custom input and output string delimiters are required, use type ErrPrefixDto.

Exchanging Error Prefix Information with User Defined Types

IBuilderErrorPrefix

Custom user defined types supporting the IBuilderErrorPrefix interface will be able to receive data from and insert data into instances of ErrPrefixDto. The following ErrPrefixDto methods interoperate with the IBuilderErrorPrefix interface:

  1. ErrPrefixDto.CopyInFromIBuilder()
  2. ErrPrefixDto.CopyOutToIBuilder()
  3. ErrPrefixDto.NewIEmpty()
  4. ErrPrefixDto.NewIEmptyWithDelimiters()
  5. ErrPrefixDto.SetIBuilder()

Taken together, these methods facilitate the import and export of error prefix and context information between ErrPrefixDto and user defined types implementing the IBuilderErrorPrefix interface.

The IBuilderErrorPrefix interface is defined as follows:

type IBuilderErrorPrefix interface {
	GetEPrefStrings() [][2]string

	SetEPrefStrings(twoDStrArray [][2]string)

	String() string
}
IBasicErrorPrefix

Custom user defined types supporting the IBasicErrorPrefix will be able to transmit error prefix information to an instance of ErrPrefixDto.

type IBasicErrorPrefix interface {
	GetEPrefStrings() [][2]string
}

The two-dimensional string array returned by GetEPrefStrings() is intended to be populated with error prefix and error context string pairs.

ErrPrefixDto methods specifically configured to handle and process IBasicErrorPrefix objects are listed as follows:

  1. ErrPrefixDto.NewIEmpty()
  2. ErrPrefixDto.NewIEmptyWithDelimiters()
  3. ErrPrefixDto.SetIBasic()
Custom Input String Delimiters

Type ErrPrefixDto allows users to configure input string delimiters used to parse input strings containing error prefix information received from external sources. This facilitates the exchange of error prefix information received from outside sources by ensuring that error prefix string components are properly separated and identified during the parsing operation. If the string delimiters for incoming strings is known, ErrPrefixDto input string delimiters can be coordinated and configured to correctly parse the incoming error prefix and error context information.

Input String Delimiters are used to parse raw string values containing error prefix and error context information. These parsing operations are routinely handled through the following methods:

  1. ErrPrefixDto.NewEPrefOld()
  2. ErrPrefixDto.NewFromStrings()
  3. ErrPrefixDto.NewFromStrings()
  4. ErrPrefixDto.NewIEmptyWithDelimiters()
  5. ErrPrefixDto.SetEPrefOld()
  6. ErrPrefixDto.XEPrefOld()
  7. ErrPrefixDto.ZEPrefOld()

Usage Examples

Test Code

Test Code is located in the errpref directory of the source code repository. All files beginning with the letters "zzzt_" and ending with "_test.go" contain test code. The errpref directory is located here: Test Code

Test Code provides many usage examples for types ErrPref and ErrPrefixDto.

Example Application

Additional code examples can be found in the Error Prefix Examples Application located at https://github.com/MikeAustin71/errorPrefixExamples. This application also contains a "Concurrency" example.

Package Configuration and Import

Go Get Command
go get github.com/MikeAustin71/errpref/@v1.7.0

​ -- or --

go get github.com/MikeAustin71/errpref/@latest
Import Configuration

import (

	erPref "github.com/MikeAustin71/errpref"
)

The import example above shows an alias of 'erPref' which is optional.

External Dependencies

None. This software package is not dependent on any external module or package.

Source Code Documentation

errpref Source Code Documentation

Tests

Source code tests are located in the errpref directory of the source code repository. All files beginning with the letters "zzzt_" and ending with "_test.go" contain test code. The errpref directory is located here: Test Code

Currently, tests show code coverage at 96%.

To run the test code, first review the command syntax in zzzzHowToRunTests.

Test results are stored in the text file, zzzzz_tests.txt

OS Support

Tests are running successfully on Windows 10 and Ubuntu 20.04 LTS.

Version

The latest version is Version 1.7.0.

As with all previous versions, this Version supports Go Modules.

This version was compiled and tested using using Go Version 1.16.4.

For more details, see the Release Notes.

Release Notes

Release Notes

License

Use of this source code is governed by the (open-source) MIT-style license which can be found in the LICENSE file located in this directory.

MIT License

Comments And Questions

Send questions or comments to:

    mike.go@paladinacs.net

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type EPrefixLineLenCalc 

type EPrefixLineLenCalc struct {
	// contains filtered or unexported fields
}

EPrefixLineLenCalc - Error Prefix Line Length Calculator This type is used to perform calculations on the line length of error prefix text output strings. Among the calculations performed, these associated methods determine how many error prefix and error context strings can be accommodated on the same line of text give a maximum line length limit.

func (*EPrefixLineLenCalc) CopyIn 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) CopyIn(
	incomingLineLenCalc *EPrefixLineLenCalc,
	ePrefix string) error

CopyIn - Receives an instance of type EPrefixLineLenCalc and proceeds to copy the internal member data variable values to the current EPrefixLineLenCalc instance.

----------------------------------------------------------------

Input Parameters 

incomingLineLenCalc        *EPrefixLineLenCalc
   - A pointer to an instance of EPrefixLineLenCalc. This method
     will NOT change the values of internal member variables
     contained in this instance.

     All data values in this EPrefixLineLenCalc instance will
     be copied to current EPrefixLineLenCalc instance
     ('ePrefixLineLenCalc').

     If this EPrefixLineLenCalc instance proves to be invalid,
     an error will be returned.

ePrefix                    string
   - This is an error prefix which is included in all returned
     error messages. Usually, it contains the names of the calling
     method or methods. Note: Be sure to leave a space at the end
     of 'ePrefix'.

------------------------------------------------------------------------

Return Values 

err                        error
   - If this method completes successfully, the returned error Type
     is set to 'nil'. If errors are encountered during processing,
     the returned error Type will encapsulate an error message.
     Note that this error message will incorporate the method
     chain and text passed by input parameter, 'ePrefix'.

func (*EPrefixLineLenCalc) CopyOut 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) CopyOut(
	ePrefix string) (
	EPrefixLineLenCalc,
	error)

CopyOut - Creates and returns a deep copy of the current EPrefixLineLenCalc. After completion of this operation, the returned copy and the current EPrefixLineLenCalc instance are identical in all respects.

------------------------------------------------------------------------

Input Parameters 

ePrefix             string
   - This is an error prefix which is included in all returned
     error messages. Usually, it contains the names of the calling
     method or methods. Note: Be sure to leave a space at the end
     of 'ePrefix'.

------------------------------------------------------------------------

Return Values 

EPrefixLineLenCalc
   - If this method completes successfully, a deep copy of the
     current EPrefixLineLenCalc instance will be returned through
     this parameter as a completely new instance of
     EPrefixLineLenCalc.

error
   - If this method completes successfully, the returned error Type
     is set to 'nil'. If errors are encountered during processing,
     the returned error Type will encapsulate an error message.
     Note that this error message will incorporate the method
     chain and text passed by input parameter, 'ePrefix'. The
     'ePrefix' text will be prefixed to the beginning of the returned
     error message.

func (*EPrefixLineLenCalc) CurrLineLenExceedsMaxLineLen 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) CurrLineLenExceedsMaxLineLen() bool

CurrLineLenExceedsMaxLineLen - If the length of the Current Line String (EPrefixLineLenCalc.currentLineStr) is greater than the Maximum Error String Length (EPrefixLineLenCalc.maxErrStringLength), this method returns 'true'. 

currentLineStrLen > maxErrStringLength == true
currentLineStrLen <= maxErrStringLength == false

func (*EPrefixLineLenCalc) EPrefWithoutContextExceedsRemainLineLen 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) EPrefWithoutContextExceedsRemainLineLen() bool

EPrefWithoutContextExceedsRemainLineLen - Returns 'true' if the length of the in-line of in-line error prefix delimiter plus the length of the error prefix string exceeds the remaining unused line length. 

in-line error prefix delimiter +
error prefix   > Remaining line Length
 This method returns 'true'.

func (*EPrefixLineLenCalc) EPrefixWithContextExceedsRemainLineLen 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) EPrefixWithContextExceedsRemainLineLen() bool

EPrefixWithContextExceedsRemainLineLen - Returns 'true' if the combination of in-line error prefix delimiter plus error prefix plus in-line error context delimiter plus error context string exceeds the remaining unused line length. 

in-line error prefix delimiter +
error prefix +
in-line error context delimiter +
error context                     > Remaining line Length
 This method returns 'true'.

func (*EPrefixLineLenCalc) Empty 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) Empty()

Empty - Sets all internal variables to their zero or uninitialized values.

IMPORTANT This method will DELETE ALL VALID DATA contained in this instance of EPrefixLineLenCalc.

func (*EPrefixLineLenCalc) Equal added in v1.6.0 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) Equal(
	lineLenCalcTwo *EPrefixLineLenCalc) bool

Equal - Returns a boolean flag signaling whether the data values contained in the current EPrefixLineLenCalc instance are equal to those contained in input parameter, 'lineLenCalcTwo'.

------------------------------------------------------------------------

Input Parameters 

lineLenCalcTwo      *EPrefixLineLenCalc
   - A pointer to an instance of EPrefixLineLenCalc. The data
     values contained in this instance will be compared to
     those contained in the current EPrefixLineLenCalc instance
     (ePrefixLineLenCalc) to determine equality.

------------------------------------------------------------------------

Return Values 

bool
   - A boolean flag signaling whether the data values contained
     in the current EPrefixLineLenCalc instance are equal to
     those contained in input parameter 'lineLenCalcTwo'. If
     the data values are equal in all respects, this returned
     boolean value will be set to 'true'.

func (*EPrefixLineLenCalc) ErrPrefixHasContext 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) ErrPrefixHasContext() bool

ErrPrefixHasContext - Returns a boolean flag signaling whether the error prefix has an associated error context.

If this method returns 'true', it means that the encapsulated error prefix DOES HAVE an associated error context string.

func (*EPrefixLineLenCalc) ErrorContextIsEmpty 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) ErrorContextIsEmpty() bool

ErrorContextIsEmpty - Returns a boolean flag signalling whether the Error Context String is an empty string.

If this method returns 'true', it means that the Error Context String is empty and has a zero string length.

func (*EPrefixLineLenCalc) ErrorPrefixIsEmpty 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) ErrorPrefixIsEmpty() bool

ErrorPrefixIsEmpty - Returns a boolean flag signalling whether the Error Prefix String is an empty string.

If this method returns 'true', it means that the Error Prefix String is empty and has a zero string length.

func (*EPrefixLineLenCalc) GetCurrLineStr 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) GetCurrLineStr() string

GetCurrLineStr - Return the current line string. This string includes the characters which have been formatted and included in a single text line but which have not yet been written out text display. As soon as the current line string fills up with characters to the maximum allowed line length, the text line will be written out to the display device.

func (*EPrefixLineLenCalc) GetCurrLineStrLength 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) GetCurrLineStrLength() uint

GetCurrLineStrLength - Returns an unsigned integer value representing the number of characters in or string length of the Current Line String.

The Current Line String contains the characters which have been collected thus far from error prefix and error context information. The current line string is used to control maximum line length and stores the characters which have not yet been written out to the text display.

As soon as the Current Line String fills up with characters to the maximum allowed line length, the text line will be written out to the display device.

func (*EPrefixLineLenCalc) GetDelimiterInLineErrContext 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) GetDelimiterInLineErrContext() string

GetDelimiterInLineErrContext - Returns the In-Line Error Context delimiter as a string.

func (*EPrefixLineLenCalc) GetDelimiterInLineErrPrefix 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) GetDelimiterInLineErrPrefix() string

GetDelimiterInLineErrPrefix - Returns the In-Line Error Prefix delimiter as a string.

func (*EPrefixLineLenCalc) GetDelimiterNewLineErrContext 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) GetDelimiterNewLineErrContext() string

GetDelimiterNewLineErrContext - Returns the New Line Error Context delimiter as a string.

func (*EPrefixLineLenCalc) GetDelimiterNewLineErrPrefix 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) GetDelimiterNewLineErrPrefix() string

GetDelimiterNewLineErrPrefix - Returns the New Line Error Prefix delimiter as a string.

func (*EPrefixLineLenCalc) GetErrorContextStr 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) GetErrorContextStr() string

GetErrorContextStr - Returns the error context string.

func (*EPrefixLineLenCalc) GetErrorPrefixStr 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) GetErrorPrefixStr() string

GetErrorPrefixStr - Returns the error prefix string.

func (*EPrefixLineLenCalc) GetMaxErrStringLength 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) GetMaxErrStringLength() uint

GetMaxErrStringLength - Returns the current the value for maximum error string length. This limit controls the line length for text displays of error prefix strings.

The value of maximum error string length is returned as an unsigned integer.

func (*EPrefixLineLenCalc) GetRemainingLineLength 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) GetRemainingLineLength() uint

GetRemainingLineLength - Returns the remaining line length. This is the difference between current line length and Maximum Error String Length. 

remainingLineLen = maxErrStringLen - currentLineStringLen

If currentLineStringLen is greater than Maximum Error String Length, the Remaining String Length is zero.

func (*EPrefixLineLenCalc) IsErrPrefixLastIndex 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) IsErrPrefixLastIndex() bool

IsErrPrefixLastIndex - Returns a boolean flag signalling whether the encapsulated ErrorPrefixInfo object is the last element in an array.

If this method returns 'true', it means that the encapsulated ErrorPrefixInfo object is the last element in an array of ErrorPrefixInfo objects.

func (*EPrefixLineLenCalc) IsValidInstance 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) IsValidInstance() bool

IsValidInstance - Returns a boolean flag signalling whether the current EPrefixLineLenCalc instance is valid, or not.

If this method returns a boolean value of 'false', it signals that the current EPrefixLineLenCalc instance is invalid.

If this method returns a boolean value of 'true', it signals that the current EPrefixLineLenCalc instance is valid in all respects.

----------------------------------------------------------------

Input Parameters 

--- NONE ---

-----------------------------------------------------------------

Return Values 

bool
   - This boolean flag signals whether the current
     EPrefixLineLenCalc instance is valid.

     If this method returns a value of 'false', it signals that
     the current EPrefixLineLenCalc instance is invalid.

     If this method returns a value of 'true', it signals that
     the current EPrefixLineLenCalc instance is valid in all
     respects.

func (*EPrefixLineLenCalc) IsValidInstanceError 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) IsValidInstanceError(
	ePrefix string) error

IsValidInstanceError - Returns an error type signalling whether the current EPrefixLineLenCalc instance is valid, or not.

If this method returns an error value NOT equal to 'nil', it signals that the current EPrefixLineLenCalc instance is invalid.

If this method returns an error value which IS equal to 'nil', it signals that the current EPrefixLineLenCalc instance is valid in all respects.

----------------------------------------------------------------

Input Parameters 

ePrefix             string
   - This is an error prefix which is included in all returned
     error messages. Usually, it contains the names of the calling
     method or methods. Note: Be sure to leave a space at the end
     of 'ePrefix'.

-----------------------------------------------------------------

Return Values 

error
   - If this returned error type is set equal to 'nil', it
     signals that the current EPrefixLineLenCalc is valid in
     all respects.

     If this returned error type is NOT equal to 'nil', it
     signals that the current EPrefixLineLenCalc is invalid.

func (EPrefixLineLenCalc) New 

func (ePrefixLineLenCalc EPrefixLineLenCalc) New() EPrefixLineLenCalc

New - Returns a new, empty instance of type EPrefixLineLenCalc.

func (EPrefixLineLenCalc) Ptr 

func (ePrefixLineLenCalc EPrefixLineLenCalc) Ptr() *EPrefixLineLenCalc

Ptr - Returns a pointer to a new, empty instance of type EPrefixLineLenCalc.

func (*EPrefixLineLenCalc) SetCurrentLineStr 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) SetCurrentLineStr(
	currentLineStr string)

SetCurrentLineStr - Sets the Current Line String. This string represents the characters which have been collected thus far from error prefix and error context information. The current line string is used to control maximum line length and stores the characters which have not yet been written out to the text display.

Be sure to set the Maximum Error String Length. Both the Current Line String and the Maximum Error String Length are essential to line length calculations.

func (*EPrefixLineLenCalc) SetEPrefDelimiters 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) SetEPrefDelimiters(
	ePrefDelimiters ErrPrefixDelimiters,
	ePrefix string) error

SetEPrefDelimiters - Sets the Error Prefix Delimiters member variable.

The Error Prefix Delimiters object stores string delimiters used to terminate error prefix and error context strings.

----------------------------------------------------------------

Input Parameters 

ePrefDelimiters     ErrPrefixDelimiters
   - An Error Prefix Delimiters object. This delimiters object
     contains information on the delimiter strings used to
     terminate error prefix and error context strings.

     type ErrPrefixDelimiters struct {
       inLinePrefixDelimiter      string
       lenInLinePrefixDelimiter   uint
       newLinePrefixDelimiter     string
       lenNewLinePrefixDelimiter  uint
       inLineContextDelimiter     string
       lenInLineContextDelimiter  uint
       newLineContextDelimiter    string
       lenNewLineContextDelimiter uint
       maxErrStringLength         uint
     }

ePrefix             string
   - This is an error prefix which is included in all returned
     error messages. Usually, it contains the names of the calling
     method or methods. Note: Be sure to leave a space at the end
     of 'ePrefix'.

-----------------------------------------------------------------

Return Values 

error
   - If this method completes successfully, the returned error
     Type is set equal to 'nil'. If errors are encountered
     during processing, the returned error Type will
     encapsulate an error message. Note that this error message
     will incorporate the method chain and text passed by input
     parameter, 'ePrefix'. The 'ePrefix' text will be prefixed
     to the beginning of the error message.

func (*EPrefixLineLenCalc) SetErrPrefixInfo 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) SetErrPrefixInfo(
	errPrefixInfo *ErrorPrefixInfo,
	ePrefix string) error

SetErrPrefixInfo - Sets the Error Prefix Information Object member variable.

The Error Prefix Information Object stores information on the error prefix and error context strings.

----------------------------------------------------------------

Input Parameters 

errPrefixInfo       *ErrorPrefixInfo
   - This Error Prefix Information Object stores information on
     the error prefix and error context strings.

     type ErrorPrefixInfo struct {
       isValid                bool
       isLastIdx              bool // Signals the last index in the array
       errorPrefixStr         string
       lenErrorPrefixStr      uint
       errPrefixHasContextStr bool
       errorContextStr        string
       lenErrorContextStr     uint
     }

ePrefix             string
   - This is an error prefix which is included in all returned
     error messages. Usually, it contains the names of the calling
     method or methods. Note: Be sure to leave a space at the end
     of 'ePrefix'.

-----------------------------------------------------------------

Return Values 

error
   - If this method completes successfully, the returned error
     Type is set equal to 'nil'. If errors are encountered
     during processing, the returned error Type will
     encapsulate an error message. Note that this error message
     will incorporate the method chain and text passed by input
     parameter, 'ePrefix'. The 'ePrefix' text will be prefixed
     to the beginning of the error message.

func (*EPrefixLineLenCalc) SetMaxErrStringLength 

func (ePrefixLineLenCalc *EPrefixLineLenCalc) SetMaxErrStringLength(
	maxErrStringLength uint)

SetMaxErrStringLength - Sets EPrefixLineLenCalc.maxErrStringLength

This method sets the value for maximum error string length. This limit controls the line length for text displays of error prefix strings.

Set this value first, before setting Current Line Length

type ErrPref 

type ErrPref struct {
	// contains filtered or unexported fields
}

ErrPref - This type is provides methods useful in formatting error prefix and error context strings.

The error prefix text is designed to be configured at the beginning of error messages and is most often used to document the thread of code execution by listing the calling sequence for specific functions and methods.

The error context string is designed to provide additional error context information associated with the currently executing function or method. Typical context information might include variable names, variable values and additional details on function execution.

Note that there are no 'pointer' methods provided for this type. This is because the type is not designed to store information. Its only function is to receive process and return strings of error prefix information.

------------------------------------------------------------------------

- IMPORTANT - None of the error prefix strings returned by the methods on this type are terminated with a new line character ('\n'). That means that none of the strings end with a new line character.

If you prefer that error prefix strings be terminated with a new line character, you have two options:

  1. Add the terminating new line character in your code.

    OR

  2. Use the Error Prefix Data Transfer Object type 'ErrPrefixDto'.

------------------------------------------------------------------------

Recommended Usage Examples 

ePrefix = ErrPref{}.EPrefCtx(
  ePrefix,
  "Tx7.TrySomethingNew()",
   "")

ePrefix = ErrPref{}.EPref(
   ePrefix,
   "Tx14.SomeFabulousAndComplexStuff()")

    actualStr := ErrPref{}.SetCtxt(
     initialStr,
      "A!=B")

Example Error Prefix String with Context information.

     "Tx1.AVeryVeryLongMethodNameCalledSomething()\\n" +
     " :  A->B\\n" +
     "Tx2.SomethingElse() : A==B\\n" +
     "Tx3.DoSomething() : A==10\\n" +
     "Tx4() : A/10==4 - Tx5() : A!=B"

func (ErrPref) ConvertNonPrintableChars 

func (ePref ErrPref) ConvertNonPrintableChars(
	nonPrintableChars []rune,
	convertSpace bool) (
	printableChars string)

ConvertNonPrintableChars - Receives a string containing non-printable characters and converts them to 'printable' characters returned in a string.

This method is primarily used for testing an evaluation.

Examples of non-printable characters are '\n', '\t' or 0x06 (Acknowledge). These example characters would be translated into printable string characters as: "\\n", "\\t" and "[ACK]".

Space characters are typically translated as " ". However, if the input parameter 'convertSpace' is set to 'true' then all spaces are converted to "[SPACE]" in the returned string.

Reference: 

https://www.juniper.net/documentation/en_US/idp5.1/topics/reference/general/intrusion-detection-prevention-custom-attack-object-extended-ascii.html

This method is useful for verifying error prefix strings which are routinely populated with non-printable characters.

------------------------------------------------------------------------

Input Parameters 

nonPrintableChars   []rune
   - An array of runes containing non-printable characters.
     The non-printable characters will be converted to
     printable characters.

convertSpace        bool
   - Space or white space characters (0x20) are by default
     translated as " ". However, if this parameter is set to
     'true', space characters will be converted to "[SPACE]".

------------------------------------------------------------------------

Return Values 

printableChars      string
   - This returned string is identical to input parameter
     'nonPrintableChars' with the exception that non-printable
     characters are translated into printable characters.

------------------------------------------------------------------------

Example Usage 

testStr := "Hello world!\n"
testRunes := []rune(testStr)
ePrefix := "theCallingFunction()"

ePrefQuark := errPrefQuark{}

actualStr :=
  ePrefQuark.
    convertNonPrintableChars(
         testRunes,
         true,
         ePrefix)

----------------------------------------------------
'actualStr' is now equal to:
   "Hello[SPACE]world!\\n"

func (ErrPref) ConvertPrintableChars added in v1.6.0 

func (ePref ErrPref) ConvertPrintableChars(
	printableChars string,
	ePrefix string) (
	nonPrintableChars []rune,
	err error)

ConvertPrintableChars - Converts printable characters to their non-printable or native equivalent. For example, instances of '\\n' in a string will be converted to '\n'.

Additional examples of converted printable string characters are: "\\n", "\\t" and "[ACK]". These printable characters be converted into their native, non-printable state: '\n', '\t' or 0x06 (Acknowledge).

Reference: 

https://www.juniper.net/documentation/en_US/idp5.1/topics/reference/general/intrusion-detection-prevention-custom-attack-object-extended-ascii.html

------------------------------------------------------------------------

Input Parameters 

printableChars      string
   - A string which may contain non-printable characters converted
     to their printable equivalents. These printable characters will
     be converted back to their native, non-printable values.

ePrefix             string
   - This is an error prefix which is included in all returned
     error messages. Usually, it contains the names of the calling
     method or methods. Note: Be sure to leave a space at the end
     of 'ePrefix'. This parameter is optional.

------------------------------------------------------------------------

Return Values 

nonPrintableChars   []rune
   - An array of runes containing non-printable characters.
     The non-printable characters were be converted from the
     printable characters contained in input parameter
     'printableChars'.

err                 error
   - If this method completes successfully, the returned error
     Type is set equal to 'nil'. If errors are encountered during
     processing, the returned error Type will encapsulate an error
     message. Note that this error message will incorporate the
     method chain and text passed by input parameter, 'ePrefix'.
     The 'ePrefix' text will be prefixed to the beginning of the
     error message.

------------------------------------------------------------------------

Example Usage 

testStr := "Hello[SPACE]world!\\n"
ePrefix := "theCallingFunction()"

ePrefQuark := errPrefQuark{}

actualRuneArray :=
  ePrefQuark.
    convertPrintableChars(
         testStr,
         ePrefix)

----------------------------------------------------
'actualRuneArray' is now equal to:
   "Hello world!\n"

func (ErrPref) EPref 

func (ePref ErrPref) EPref(
	oldErrPref string,
	newErrPref string) string

EPref - Returns a string concatenating the old error prefix the new custom, user-defined error prefix. The new error prefix is typically used to document method or function chains in error messages.

The old error prefix contains the function chain or series which led to the function next in line for execution.

The error prefix text is designed to be configured at the beginning of error messages and is most often used to document the thread of code execution by listing the calling sequence for specific functions and methods.

- IMPORTANT -

The last line of error prefix strings returned by the methods on this type are NOT terminated with a new line character ('\n'). That means that the last line of error prefix strings will never end with a new line character ('\n').

If you prefer that the last line of error prefix strings be terminated with a new line character ('\n'), you have two options:

  1. Add the terminating new line character in your code.

    OR

  2. Use the Error Prefix Data Transfer Object type 'ErrPrefixDto'.

----------------------------------------------------------------

Input Parameters 

oldErrPref          string
   - This includes the previous or preexisting error prefix
     string. This string will be parsed into error prefix
     and error context components before being converted into
     a single, formatted string containing error prefix and
     error context information.

     This string should consist of a series of error prefix
     strings. Error prefixes should be delimited using system
     default string delimiters.

     The system default string delimiters for error prefix
     elements are listed as follows:
        New Line Error Prefix Delimiter = "\n"
        In-Line Error Prefix Delimiter  = " - "

     If this string contains associated error context strings
     as well, they should be delimited using the same system
     default string delimiters for error context elements:
        New Line Error Context Delimiter = "\n :  "
        In-Line Error Context Delimiter = " : "

newErrPref          string
   - The new error prefix represents typically identifies
     the function or method which is currently executing. This
     information is used to document source code execution flow
     in error messages.

     If 'newErrPref' equates to an empty string, this method will
     return the formatted version of 'oldErrPref' and no new error
     prefix information will be added.

-----------------------------------------------------------------

Return Values 

string
   - This method will return the consolidated error prefix text.

     The error prefix text is designed to be configured at the
     beginning of error messages and is most often used to
     document the thread of code execution by listing the calling
     sequence for specific functions and methods.

func (ErrPref) EPrefCtx 

func (ePref ErrPref) EPrefCtx(
	oldErrPref string,
	newErrPref string,
	newContext string) string

EPrefCtx - Receives an old error prefix, new error prefix and a new context string which are concatenated and returned as a combined string.

Error prefix text is designed to be configured at the beginning of error messages and is most often used to document the thread of code execution by listing the calling sequence for a specific list of functions and methods.

The error context string is designed to provide additional information about the function or method identified by the associated error prefix string. Typical context information might include variable names, variable values and additional details on function execution.

- IMPORTANT -

The last line of error prefix strings returned by the methods on this type are NOT terminated with a new line character ('\n'). That means that the last line of error prefix strings will never end with a new line character ('\n').

If you prefer that the last line of error prefix strings be terminated with a new line character ('\n'), you have two options:

  1. Add the terminating new line character in your code.

    OR

  2. Use the Error Prefix Data Transfer Object type 'ErrPrefixDto'.

----------------------------------------------------------------

Input Parameters 

oldErrPref          string
   - This includes the previous or preexisting error prefix
     string. This string will be parsed into error prefix
     and error context components before being converted into
     a single, formatted string containing error prefix and
     error context information.

     This string should consist of a series of error prefix
     strings. Error prefixes should be delimited using system
     default string delimiters.

     The system default string delimiters for error prefix
     elements are listed as follows:
        New Line Error Prefix Delimiter = "\n"
        In-Line Error Prefix Delimiter  = " - "

     If this string contains associated error context strings
     as well, they should be delimited using the same system
     default string delimiters for error context elements:
        New Line Error Context Delimiter = "\n :  "
        In-Line Error Context Delimiter = " : "

newErrPref          string
   - The new error prefix represents the error prefix string
     associated with the function or method which is currently
     executing. This parameter is optional and will accept an
     empty string, but there isn't much point in calling this
     method without a substantive value for 'newErrPref'.

newContext          string
   - This is the error context information associated with the
     new error prefix ('newErrPref'). This parameter is
     optional and will accept an empty string.

-----------------------------------------------------------------

Return Values 

string
   - This method will return the consolidated error prefix text.

     The error prefix text is designed to be configured at the
     beginning of error messages and is most often used to
     document the thread of code execution by listing the calling
     sequence for specific functions and methods.

-----------------------------------------------------------------

Usage Examples 

errorPrefix = ErrPref{}.EPrefCtx(
                         oldErrPref, // Assuming this is the old
                                      // error prefix
                         newErrPref,
                         newContext)

func (ErrPref) EPrefOld 

func (ePref ErrPref) EPrefOld(
	oldErrPref string) string

EPrefOld - Receives an old or preexisting error prefix string which is parsed into error prefix and error context components and returned as a properly formatted error prefix string.

Error prefix text is designed to be configured at the beginning of error messages and is most often used to document the thread of code execution by listing the calling sequence for a specific list of functions and methods.

The error context string is designed to provide additional information about the function or method identified by the associated error prefix string. Typical context information might include variable names, variable values and additional details on function execution.

- IMPORTANT -

The last line of error prefix strings returned by the methods on this type are NOT terminated with a new line character ('\n'). That means that the last line of error prefix strings will never end with a new line character ('\n').

If you prefer that the last line of error prefix strings be terminated with a new line character ('\n'), you have two options:

  1. Add the terminating new line character in your code.

    OR

  2. Use the Error Prefix Data Transfer Object type 'ErrPrefixDto'.

----------------------------------------------------------------

Input Parameters 

oldErrPref          string
   - This includes the previous or preexisting error prefix
     string. This string will be parsed into error prefix
     and error context components before being converted into
     a single, formatted string containing error prefix and
     error context information.

     This string should consist of a series of error prefix
     strings. Error prefixes should be delimited using system
     default string delimiters.

     The system default string delimiters for error prefix
     elements are listed as follows:
        New Line Error Prefix Delimiter = "\n"
        In-Line Error Prefix Delimiter  = " - "

     If this string contains associated error context strings
     as well, they should be delimited using the same system
     default string delimiters for error context elements:
        New Line Error Context Delimiter = "\n :  "
        In-Line Error Context Delimiter = " : "

-----------------------------------------------------------------

Return Values 

string
   - This method will return the consolidated error prefix text.

     The error prefix text is designed to be configured at the
     beginning of error messages and is most often used to
     document the thread of code execution by listing the calling
     sequence for specific functions and methods.

-----------------------------------------------------------------

Usage Examples 

errorPrefix = ErrPref{}.EPrefOld(
                         oldErrPref) // Assuming this is the old
                                     // or preexisting error
                                     // prefix

func (ErrPref) FmtStr 

func (ePref ErrPref) FmtStr(
	errPref string) string

FmtStr - Returns a formatted text representation of all error prefix and error context information contained in the input parameter string, 'errPref'.

Error prefix text is designed to be configured at the beginning of error messages and is most often used to document the thread of code execution by listing the calling sequence for a specific list of functions and methods.

The error context descriptive text provides additional information about the function or method identified in the associated error prefix string. Typical context information might include variable names, variable values and further details on function execution.

The returned formatted text is generated using system default string delimiters.

The system default string delimiters are listed as follows: 

New Line Error Prefix Delimiter = "\n"
In-Line Error Prefix Delimiter  = " - "
New Line Error Context Delimiter = "\n :  "
In-Line Error Context Delimiter = " : "

------------------------------------------------------------------------

Input Parameters 

errPref             string
   - This string holds a series of error prefix and error
     context text elements. Each element must be separated by
     either a new line character '\n' or the string " - ". This
     will format these elements and return them in a properly
     configured error prefix string for text presentation.

------------------------------------------------------------------------

Return Values 

string
   - A string containing properly formatted error prefix and
     error context pairs configured for configuration in an
     error message.

func (ErrPref) GetDelimiters added in v1.6.0 

func (ePref ErrPref) GetDelimiters() ErrPrefixDelimiters

GetDelimiters - Returns an ErrPrefixDelimiters object containing the string delimiters used to delimit error prefix and error context elements with strings.

The ErrPref type uses the system default string delimiters for parsing both input and output error prefix and context strings.

The system default string delimiters are listed as follows: 

New Line Error Prefix Delimiter = "\n"
In-Line Error Prefix Delimiter  = " - "
New Line Error Context Delimiter = "\n :  "
In-Line Error Context Delimiter = " : "

func (ErrPref) GetLastEPref 

func (ePref ErrPref) GetLastEPref(
	oldErrPrefix string) string

GetLastEPref - Returns the last error prefix, error context pair from a string consisting of a series of error prefix, error context pairs.

The input parameter 'oldErrPrefix' will be parsed and the last error prefix and error context pair will be identified using system default string delimiters.

The system default string delimiters are listed as follows: 

New Line Error Prefix Delimiter = "\n"
In-Line Error Prefix Delimiter  = " - "
New Line Error Context Delimiter = "\n :  "
In-Line Error Context Delimiter = " : "

func (ErrPref) GetMaxErrPrefTextLineLength 

func (ePref ErrPref) GetMaxErrPrefTextLineLength() (
	maxErrPrefixStringLength uint)

GetMaxErrPrefTextLineLength - Returns the current maximum number of characters allowed in an error prefix text line output display.

To change or reset this maximum limit value, see method: 

ErrPref.SetMaxErrPrefTextLineLength().

------------------------------------------------------------------------

Input Parameters 

--- NONE ---

------------------------------------------------------------------------

Return Values 

maxErrPrefixStringLength      uint
   - This method will return an unsigned integer value
     specifying the maximum number of characters allowed
     in an error prefix text display line.

func (ErrPref) SetCtxt 

func (ePref ErrPref) SetCtxt(
	oldErrPref string,
	newErrContext string) string

SetCtxt - Sets or resets the error context for the last error prefix. This operation either adds, or replaces, the error context string associated with the last error prefix in input parameter, 'oldErrPref'.

If the last error prefix already has an error context string, it will be replaced by input parameter, 'newErrContext'.

If the last error prefix does NOT have an associated error context, this new error context string will be associated with that error prefix.

- IMPORTANT -

The last line of error prefix strings returned by the methods on this type are NOT terminated with a new line character ('\n'). That means that the last line of error prefix strings will never end with a new line character ('\n').

If you prefer that the last line of error prefix strings be terminated with a new line character ('\n'), you have two options:

  1. Add the terminating new line character in your code.

    OR

  2. Use the Error Prefix Data Transfer Object type 'ErrPrefixDto'.

----------------------------------------------------------------

Input Parameters 

oldErrPref          string
   - This includes the previous or preexisting error prefix
     string. This string will be parsed into error prefix
     and error context components before being converted into
     a single, formatted string containing error prefix and
     error context information.

     This string should consist of a series of error prefix
     strings. Error prefixes should be delimited using system
     default string delimiters.

     The system default string delimiters for error prefix
     elements are listed as follows:
        New Line Error Prefix Delimiter = "\n"
        In-Line Error Prefix Delimiter  = " - "

     If this string contains associated error context strings
     as well, they should be delimited using the same system
     default string delimiters for error context elements:
        New Line Error Context Delimiter = "\n :  "
        In-Line Error Context Delimiter = " : "

newErrContext       string
   - This string holds the new error context information. If
     the last error prefix in 'oldErrPref' already has an
     associated error context, that context will be deleted and
     replaced by 'newErrContext'. If, however, the last error
     prefix in 'oldErrPref' does NOT have an associated error
     context, this 'newErrContext' string will be added and
     associated with the last error prefix in 'oldErrPref'.

-----------------------------------------------------------------

Return Values 

string
   - This method will return the consolidated error prefix text.

     The error prefix text is designed to be configured at the
     beginning of error messages and is most often used to
     document the thread of code execution by listing the calling
     sequence for specific functions and methods.

func (ErrPref) SetMaxErrPrefTextLineLength 

func (ePref ErrPref) SetMaxErrPrefTextLineLength(
	maxErrPrefixTextLineLength uint)

SetMaxErrPrefTextLineLength - Sets the maximum limit on the number of characters allowed in an error prefix text line output display.

-IMPORTANT - Setting this value will control the maximum character limit not only for this ErrPref instance, but will also control all that limit for all other instances of ErrPref created in this session.

----------------------------------------------------------------

Input Parameters 

maxErrPrefixTextLineLength      uint
   - This unsigned integer value will be used to set the
     maximum number of characters allowed in a text display
     line for error prefix information.

     If 'maxErrPrefixTextLineLength' is set to a value of zero
     (0), this method will take no action and return.

-----------------------------------------------------------------

Return Values 

--- NONE ---

func (ErrPref) SetMaxErrPrefTextLineLengthToDefault 

func (ePref ErrPref) SetMaxErrPrefTextLineLengthToDefault()

SetMaxErrPrefTextLineLengthToDefault - Maximum Error Prefix Line Length is the maximum limit on the number of characters allowed in a single error prefix text line.

This method resets that maximum limit to its default value of 40-characters.

type ErrPrefixDelimiters 

type ErrPrefixDelimiters struct {
	// contains filtered or unexported fields
}

ErrPrefixDelimiters - This type is used to store and transport the string delimiters used in parsing error prefix and error context strings.

func (*ErrPrefixDelimiters) CopyIn 

func (ePrefDelims *ErrPrefixDelimiters) CopyIn(
	incomingDelimiters *ErrPrefixDelimiters,
	ePrefix string) error

CopyIn - Receives an instance of type ErrPrefixDelimiters and proceeds to copy the internal member data variable values to the current ErrPrefixDelimiters instance.

----------------------------------------------------------------

Input Parameters 

incomingDelimiters         *ErrPrefixDelimiters
   - A pointer to an instance of ErrPrefixDelimiters. This method
     will NOT change the values of internal member variables
     contained in this instance.

     All data values in this ErrPrefixDelimiters instance will
     be copied to current ErrPrefixDelimiters instance
     ('ePrefDelims').

     If this ErrPrefixDelimiters instance proves to be invalid,
     an error will be returned.

ePrefix                    string
   - This is an error prefix which is included in all returned
     error messages. Usually, it contains the names of the calling
     method or methods. Note: Be sure to leave a space at the end
     of 'ePrefix'.

------------------------------------------------------------------------

Return Values 

err                        error
   - If this method completes successfully, the returned error Type
     is set to 'nil'. If errors are encountered during processing,
     the returned error Type will encapsulate an error message.
     Note that this error message will incorporate the method
     chain and text passed by input parameter, 'ePrefix'.

func (*ErrPrefixDelimiters) CopyOut 

func (ePrefDelims *ErrPrefixDelimiters) CopyOut(
	ePrefix string) (
	ErrPrefixDelimiters,
	error)

CopyOut - Creates and returns a deep copy of the current ErrPrefixDelimiters. After completion of this operation, the returned copy and the current ErrPrefixDelimiters instance are identical in all respects.

------------------------------------------------------------------------

Input Parameters 

ePrefix             string
   - This is an error prefix which is included in all returned
     error messages. Usually, it contains the names of the calling
     method or methods. Note: Be sure to leave a space at the end
     of 'ePrefix'.

------------------------------------------------------------------------

Return Values 

ErrPrefixDelimiters
   - If this method completes successfully, a deep copy of the
     current ErrPrefixDelimiters instance will be returned through
     this parameter as a completely new instance of
     ErrPrefixDelimiters.

error
   - If this method completes successfully, the returned error Type
     is set to 'nil'. If errors are encountered during processing,
     the returned error Type will encapsulate an error message.
     Note that this error message will incorporate the method
     chain and text passed by input parameter, 'ePrefix'. The
     'ePrefix' text will be prefixed to the beginning of the returned
     error message.

func (*ErrPrefixDelimiters) Empty added in v1.6.0 

func (ePrefDelims *ErrPrefixDelimiters) Empty()

Empty - This method will overwrite and reset all internal member variables to their zero values.

func (*ErrPrefixDelimiters) Equal added in v1.6.0 

func (ePrefDelims *ErrPrefixDelimiters) Equal(
	incomingDelimiters *ErrPrefixDelimiters) (
	areEqual bool)

Equal - Receives a pointer to an instance of ErrPrefixDelimiters and proceeds to determine whether the data values encapsulated in that instance are equal to those in the current ErrPrefixDelimiters instance.

----------------------------------------------------------------

Input Parameters 

incomingDelimiters  *ErrPrefixDelimiters
   - A pointer to an instance of ErrPrefixDelimiters. The
     internal data values encapsulated by this object will be
     compared to those contained in the current
     ErrPrefixDelimiters instance. If the data values are
     equal, a boolean flag of 'true' will be returned.

------------------------------------------------------------------------

Return Values 

areEqual            bool
   - This method will compare the data values encapsulated by
     the input parameter, 'incomingDelimiters' and the current
     ErrPrefixDelimiters instance. If the data values are
     equivalent, this boolean flag will be set to 'true'.

     If the data values are NOT equivalent, this parameter will
     be set to 'false'.

func (*ErrPrefixDelimiters) GetInLineContextDelimiter 

func (ePrefDelims *ErrPrefixDelimiters) GetInLineContextDelimiter() string

GetInLineContextDelimiter - Returns ePrefDelims.inLineContextDelimiter

func (*ErrPrefixDelimiters) GetInLinePrefixDelimiter 

func (ePrefDelims *ErrPrefixDelimiters) GetInLinePrefixDelimiter() string

GetInLinePrefixDelimiter - Returns ePrefDelims.inLinePrefixDelimiter

func (*ErrPrefixDelimiters) GetLengthInLineContextDelimiter 

func (ePrefDelims *ErrPrefixDelimiters) GetLengthInLineContextDelimiter() uint

GetLengthInLineContextDelimiter - Returns the number of characters in the 'In Line Context Delimiter' string as an unsigned integer.

func (*ErrPrefixDelimiters) GetLengthInLinePrefixDelimiter 

func (ePrefDelims *ErrPrefixDelimiters) GetLengthInLinePrefixDelimiter() uint

GetLengthInLinePrefixDelimiter - Returns the number of characters in the 'In Line Prefix Delimiter' string as an unsigned integer.

func (*ErrPrefixDelimiters) GetLengthNewLineContextDelimiter 

func (ePrefDelims *ErrPrefixDelimiters) GetLengthNewLineContextDelimiter() uint

GetLengthNewLineContextDelimiter - Returns the number of characters in the 'New Line Context Delimiter' string as an unsigned integer.

func (*ErrPrefixDelimiters) GetLengthNewLinePrefixDelimiter 

func (ePrefDelims *ErrPrefixDelimiters) GetLengthNewLinePrefixDelimiter() uint

GetLengthNewLinePrefixDelimiter - Returns the number of characters in the 'New Line Prefix Delimiter' string as an unsigned integer.

func (*ErrPrefixDelimiters) GetNewLineContextDelimiter 

func (ePrefDelims *ErrPrefixDelimiters) GetNewLineContextDelimiter() string

GetNewLineContextDelimiter - Returns ePrefDelims.newLineContextDelimiter

func (*ErrPrefixDelimiters) GetNewLinePrefixDelimiter 

func (ePrefDelims *ErrPrefixDelimiters) GetNewLinePrefixDelimiter() string

GetNewLinePrefixDelimiter - Returns ePrefDelims.newLinePrefixDelimiter

func (*ErrPrefixDelimiters) IsValidInstance 

func (ePrefDelims *ErrPrefixDelimiters) IsValidInstance() bool

IsValidInstance - Returns a boolean flag signalling whether the current ErrPrefixDelimiters instance is valid, or not.

If this method returns a boolean value of 'false', it signals that the current ErrPrefixDelimiters instance is invalid.

If this method returns a boolean value of 'true', it signals that the current ErrPrefixDelimiters instance is valid in all respects.

----------------------------------------------------------------

Input Parameters 

--- NONE ---

-----------------------------------------------------------------

Return Values 

bool
   - This boolean flag signals whether the current
     ErrPrefixDelimiters instance is valid.

     If this method returns a value of 'false', it signals that
     the current ErrPrefixDelimiters instance is invalid.

     If this method returns a value of 'true', it signals that
     the current ErrPrefixDelimiters instance is valid in all
     respects.

func (*ErrPrefixDelimiters) IsValidInstanceError 

func (ePrefDelims *ErrPrefixDelimiters) IsValidInstanceError(
	ePrefix string) error

IsValidInstanceError - Returns an error type signalling whether the current ErrPrefixDelimiters instance is valid, or not.

If this method returns an error value NOT equal to 'nil', it signals that the current ErrPrefixDelimiters instance is invalid.

If this method returns an error value which IS equal to 'nil', it signals that the current ErrPrefixDelimiters instance is valid in all respects.

----------------------------------------------------------------

Input Parameters 

ePrefix             string
   - This is an error prefix which is included in all returned
     error messages. Usually, it contains the names of the calling
     method or methods. Note: Be sure to leave a space at the end
     of 'ePrefix'.

-----------------------------------------------------------------

Return Values 

error
   - If this returned error type is set equal to 'nil', it
     signals that the current ErrPrefixDelimiters is valid in
     all respects.

     If this returned error type is NOT equal to 'nil', it
     signals that the current ErrPrefixDelimiters is invalid.

func (ErrPrefixDelimiters) New added in v1.6.0 

func (ePrefDelims ErrPrefixDelimiters) New(
	newLinePrefixDelimiters string,
	inLinePrefixDelimiters string,
	newLineContextDelimiters string,
	inLineContextDelimiters string,
	ePrefix string) (
	ErrPrefixDelimiters,
	error)

New - Returns a new instance of ErrPrefixDelimiters generated from the string values passed as input parameters.

----------------------------------------------------------------

Input Parameters 

newLinePrefixDelimiters    string
   - The contents of this string will be used to parse error
     prefix strings on separate lines of text.

     If an empty string (string length zero) is passed for this
     parameter, an error will be returned.

inLinePrefixDelimiters     string
   - The contents of this string will be used to separate
     multiple error prefix elements within a single line of
     text.

     If an empty string (string length zero) is passed for this
     parameter, an error will be returned.

newLineContextDelimiters   string
   - The contents of this string will be used to parse error
     context elements on separate lines of text.

     If an empty string (string length zero) is passed for this
     parameter, an error will be returned.

inLineContextDelimiters    string
   - The contents of this string will be used to separate
     multiple error context elements within a single line of
     text.

     If an empty string (string length zero) is passed for this
     parameter, an error will be returned.

ePrefix                    string
   - A string containing the name of the function which called
     this method. If an error occurs this string will be
     prefixed to the beginning of the returned error message.

     This parameter is optional. If an error prefix is not
     required, submit an empty string for this parameter ("").

     If an empty string (string length zero) is passed for this
     parameter, an error will be returned.

-----------------------------------------------------------------

Return Values 

ErrPrefixDelimiters
   - If this method completes successfully, this parameter will
     return a new fully populated instance of
     ErrPrefixDelimiters.

error
   - If this method completes successfully, the returned error
     Type is set equal to 'nil'.

     If errors are encountered during processing, the returned
     error Type will encapsulate an error message.

     In the event of an error, the value of parameter
     'ePrefix' will be prefixed and attached to the beginning
     of the error message.

func (ErrPrefixDelimiters) NewDefaults added in v1.6.0 

func (ePrefDelims ErrPrefixDelimiters) NewDefaults() ErrPrefixDelimiters

NewDefaults - Returns a new instance of ErrPrefixDelimiters populated with system default values for string delimiters.

The system default string delimiters are listed as follows: 

New Line Error Prefix Delimiter = "\n"
In-Line Error Prefix Delimiter  = " - "
New Line Error Context Delimiter = "\n :  "
In-Line Error Context Delimiter = " : "

String delimiters are used to parse raw input strings and separate error prefix and error context elements. In addition, string delimiters are used to join error prefix and error context elements for output or presentation text.

func (*ErrPrefixDelimiters) SetDelimiters added in v1.6.0 

func (ePrefDelims *ErrPrefixDelimiters) SetDelimiters(
	newLinePrefixDelimiters string,
	inLinePrefixDelimiters string,
	newLineContextDelimiters string,
	inLineContextDelimiters string,
	ePrefix string) error

SetDelimiters - Overwrites and replaces the data values for all internal member variables in the current ErrPrefixDelimiters instance.

The new data values are generated from string values submitted as input parameters.

IMPORTANT All existing delimiter information in this ErrPrefixDelimiters instance will be overwritten, deleted and replaced.

----------------------------------------------------------------

Input Parameters 

newLinePrefixDelimiters    string
   - The contents of this string will be used to parse error
     prefix strings on separate lines of text.

     If an empty string (string length zero) is passed for this
     parameter, an error will be returned.

inLinePrefixDelimiters     string
   - The contents of this string will be used to separate
     multiple error prefix elements within a single line of
     text.

     If an empty string (string length zero) is passed for this
     parameter, an error will be returned.

newLineContextDelimiters   string
   - The contents of this string will be used to parse error
     context elements on separate lines of text.

     If an empty string (string length zero) is passed for this
     parameter, an error will be returned.

inLineContextDelimiters    string
   - The contents of this string will be used to separate
     multiple error context elements within a single line of
     text.

     If an empty string (string length zero) is passed for this
     parameter, an error will be returned.

ePrefix                    string
   - A string containing the name of the function which called
     this method. If an error occurs this string will be
     prefixed to the beginning of the returned error message.

     This parameter is optional. If an error prefix is not
     required, submit an empty string for this parameter ("").

-----------------------------------------------------------------

Return Values 

error
   - If this method completes successfully, the returned error
     Type is set equal to 'nil'.

     If errors are encountered during processing, the returned
     error Type will encapsulate an error message.

     In the event of an error, the value of parameter
     'ePrefix' will be prefixed and attached to the beginning
     of the error message.

func (*ErrPrefixDelimiters) SetInLineContextDelimiter 

func (ePrefDelims *ErrPrefixDelimiters) SetInLineContextDelimiter(
	inLineContextDelimiter string)

SetInLineContextDelimiter - Sets ePrefDelims.inLineContextDelimiter

This method also sets the line length value for this parameter and stores it in an internal member variable. This value may be accessed through a 'Getter' method.

func (*ErrPrefixDelimiters) SetInLinePrefixDelimiter 

func (ePrefDelims *ErrPrefixDelimiters) SetInLinePrefixDelimiter(
	inLinePrefixDelimiter string)

SetInLinePrefixDelimiter - Sets ePrefDelims.inLinePrefixDelimiter

This method also sets the line length value for this parameter and stores it in an internal member variable. This value may be accessed through a 'Getter' method.

func (*ErrPrefixDelimiters) SetLineLengthValues 

func (ePrefDelims *ErrPrefixDelimiters) SetLineLengthValues()

SetLineLengthValues - Automatically calculates, sets and stores the line lengths for all delimiters. These values are stored in internal member variables and may be accessed using 'Getter' methods.

func (*ErrPrefixDelimiters) SetNewLineContextDelimiter 

func (ePrefDelims *ErrPrefixDelimiters) SetNewLineContextDelimiter(
	newLineContextDelimiter string)

SetNewLineContextDelimiter - Sets ePrefDelims.newLineContextDelimiter

This method also sets the line length value for this parameter and stores it in an internal member variable. This value may be accessed through a 'Getter' method.

func (*ErrPrefixDelimiters) SetNewLinePrefixDelimiter 

func (ePrefDelims *ErrPrefixDelimiters) SetNewLinePrefixDelimiter(
	newLinePrefixDelimiter string)

SetNewLinePrefixDelimiter - Sets ePrefDelims.newLinePrefixDelimiter

This method also sets the line length value for this parameter and stores it in an internal member variable. This value may be accessed through a 'Getter' method.

func (*ErrPrefixDelimiters) SetToDefault added in v1.6.0 

func (ePrefDelims *ErrPrefixDelimiters) SetToDefault()

SetToDefault - Sets the values of the current ErrPrefixDelimiters instance to those of the system defaults.

The system default string delimiters are listed as follows: 

New Line Error Prefix Delimiter = "\n"
In-Line Error Prefix Delimiter  = " - "
New Line Error Context Delimiter = "\n :  "
In-Line Error Context Delimiter = " : "

func (*ErrPrefixDelimiters) SetToDefaultIfEmpty added in v1.6.0 

func (ePrefDelims *ErrPrefixDelimiters) SetToDefaultIfEmpty()

SetToDefaultIfEmpty - Sets the values of the current ErrPrefixDelimiters instance to those of the system defaults if the current instance is empty or invalid.

The system default string delimiters are listed as follows: 

New Line Error Prefix Delimiter = "\n"
In-Line Error Prefix Delimiter  = " - "
New Line Error Context Delimiter = "\n :  "
In-Line Error Context Delimiter = " : "

func (ErrPrefixDelimiters) String added in v1.6.0 

func (ePrefDelims ErrPrefixDelimiters) String() string

String - Returns a string listing the values of the member variables for the current ErrPrefixDelimiters instance.

type ErrPrefixDto 

type ErrPrefixDto struct {
	// contains filtered or unexported fields
}

ErrPrefixDto - Error Prefix Data Transfer Object. This type encapsulates and formats error prefix and error context strings.

The error prefix text is designed to be configured at the beginning of error messages and is most often used to document the thread of code execution by listing the calling sequence for specific functions and methods.

The error context string is designed to provide additional error context information associated with the currently executing function or method. Typical context information might include variable names, variable values and additional details on function execution.

ErrPrefixDto is similar in function to type 'ErrPref'. However, unlike 'ErrPref', ErrPrefixDto is configured encapsulate and transmit error prefix information between methods. 'ErrPref' only returns strings. This type, ErrPrefixDto, returns an object which may be exchanged between methods.

func (*ErrPrefixDto) AddEPrefCollectionStr 

func (ePrefDto *ErrPrefixDto) AddEPrefCollectionStr(
	errorPrefixCollectionStr string) (
	numberOfCollectionItemsParsed int)

AddEPrefCollectionStr - Receives a string containing one or more error prefix and error context pairs. This error prefix information is parsed and added to the internal store of error prefix elements.

The incoming collection of error prefix information is added to the END of the collection maintained by the current ErrPrefixDto instance.

Upon completion this method returns an integer value identifying the number of error prefix elements successfully parsed and added to internal error prefix storage.

----------------------------------------------------------------

Input Parameters 

errorPrefixCollectionStr      string
   - A string consisting of a series of error prefix strings.
     Error prefixes should be delimited by either a new line
     character ('\n') or the in-line delimiter string, " - ".

     If the collection string contains error context strings
     as well, they should be delimited with either a new line
     delimiter string, "\n :  " or an in-line delimiter string,
     " : ".

-----------------------------------------------------------------

Return Values 

numberOfCollectionItemsParsed int
   - This returned integer value contains the number of error
     prefix elements parsed from input parameter
     'errorPrefixCollection' and added to the internal store
     of error prefix elements.

func (*ErrPrefixDto) AddEPrefStrings added in v1.5.0 

func (ePrefDto *ErrPrefixDto) AddEPrefStrings(
	twoDStrArray [][2]string)

AddEPrefStrings - Adds error prefix information extracted from a passed two-dimensional string array to the internal ErrorPrefixInfo collection managed by this ErrPrefixDto instance.

The incoming collection of error prefix information is added to the END of the collection maintained by the current ErrPrefixDto instance.

If input parameter 'twoDStrArray' is 'nil' or empty, this method will take no action an exit.

func (*ErrPrefixDto) ClearLeadingTextStr added in v1.7.0 

func (ePrefDto *ErrPrefixDto) ClearLeadingTextStr()

ClearLeadingTextStr - Clears or resets the internal member variable, 'leadingTextStr' to a zero length or empty string.

The leading text string is a string supplied by the user which is stored in the current instance of ErrPrefixDto. It is used to add a string of text characters to the beginning of formatted error prefix text displays.

When the output methods ErrPrefixDto.StrMaxLineLen() or ErrPrefixDto.String() are called to display error prefix information, the leading text string will be appended to the beginning of that error prefix text display.

The default for the leading text string is a zero length or empty string. To clear or reset the leading text string to an empty string, call this method, ErrPrefixDto.ClearLeadingTextStr().

The value of the leading text string is set by calling the method, ErrPrefixDto.SetLeadingTextStr().

Calling this method, ErrPrefixDto.ClearLeadingTextStr(), will effectively erase and remove any text characters previously configured in the leading text string.

func (*ErrPrefixDto) ClearTrailingTextStr added in v1.7.0 

func (ePrefDto *ErrPrefixDto) ClearTrailingTextStr()

ClearTrailingTextStr - Clears or resets the internal member variable, 'trailingTextStr' to a zero length or empty string.

The trailing text string is a string supplied by the user which is stored in the current instance of ErrPrefixDto. It is used to add a string of text characters to the end of formatted error prefix text displays.

When the output methods ErrPrefixDto.StrMaxLineLen() or ErrPrefixDto.String() are called to display error prefix information, the trailing text string will be appended to the end of that error prefix text display.

The default for the trailing text string is a zero length or empty string. To clear or reset the trailing text string to an empty string, call this method, ErrPrefixDto.ClearTrailingTextStr().

The value of the trailing text string is set by calling the method, ErrPrefixDto.SetTrailingTextStr().

Calling this method, ErrPrefixDto.ClearTrailingTextStr(), will effectively erase and remove any text characters previously configured in the trailing text string.

func (*ErrPrefixDto) Copy added in v1.2.0 

func (ePrefDto *ErrPrefixDto) Copy() ErrPrefixDto

Copy - Creates a deep copy of the data fields contained in the current ErrPrefixDto instance, and returns that data as a as a new instance of ErrPrefixDto.

------------------------------------------------------------------------

Input Parameters 

--- NONE ---

------------------------------------------------------------------------

Return Values 

ErrPrefixDto
   - If this method completes successfully, a deep copy of the
     current ErrPrefixDto instance will be returned through
     this parameter as a pointer to a new instance of
     ErrPrefixDto.

func (*ErrPrefixDto) CopyIn 

func (ePrefDto *ErrPrefixDto) CopyIn(
	inComingErrPrefixDto *ErrPrefixDto,
	eMsg string) error

CopyIn - Copies the data fields from an incoming instance of ErrPrefixDto ('inComingErrPrefixDto') to the data fields of the current ErrPrefixDto instance ('ePrefDto').

All of the data fields in current ErrPrefixDto instance ('ePrefDto') will be modified and overwritten.

IMPORTANT All existing error prefix and error context information in this ErrPrefixDto instance will be overwritten and deleted.

----------------------------------------------------------------

Input Parameters 

inComingErrPrefixDto       *ErrPrefixDto
   - A pointer to an instance of ErrPrefixDto. This method
     will NOT change the values of internal member variables
     contained in this instance.

     All data values in this ErrPrefixDto instance will be
     copied to current ErrPrefixDto instance
     ('ePrefDto').

eMsg                string
   - This is an error prefix which is included in all returned
     error messages returned by this method. Usually, it
     contains the names of the calling method or methods.

     Note: Be sure to leave a space at the end of 'eMsg'.
     This parameter is optional.

------------------------------------------------------------------------

Return Values 

err                        error
   - If this method completes successfully, the returned error Type
     is set to 'nil'. If errors are encountered during processing,
     the returned error Type will encapsulate an error message.
     Note that this error message will incorporate the method
     chain and text passed by input parameter, 'eMsg'.

func (*ErrPrefixDto) CopyInFromIBuilder added in v1.6.0 

func (ePrefDto *ErrPrefixDto) CopyInFromIBuilder(
	inComingIBuilder IBuilderErrorPrefix,
	eMsg string) error

CopyInFromIBuilder - Receives an object implementing the IBuilderErrorPrefix interface and proceeds copy its error prefix and error context information into the current instance of ErrPrefixDto.

IMPORTANT All existing error prefix and error context information in this ErrPrefixDto instance will be overwritten and deleted.

This means that if IBuilderErrorPrefix parameter, 'inComingIBuilder' generates an empty set of error prefix error prefix information, the current ErrPrefixDto instance will likewise be configured with an identical empty set of error prefix information.

----------------------------------------------------------------

Input Parameters 

inComingIBuilder    IBuilderErrorPrefix
   - Any object which implements the IBuilderErrorPrefix
     interface.

eMsg                string
   - This is an error prefix which is included in all returned
     error messages returned by this method. Usually, it
     contains the names of the calling method or methods.

     Note: Be sure to leave a space at the end of 'eMsg'.
     This parameter is optional.

-----------------------------------------------------------------

Return Values 

error
   - If this method completes successfully, the returned error Type
     is set to 'nil'. If errors are encountered during processing,
     the returned error Type will encapsulate an error message.
     Note that this error message will incorporate the method
     chain and text passed by input parameter, 'eMsg'.

func (*ErrPrefixDto) CopyOut 

func (ePrefDto *ErrPrefixDto) CopyOut(
	eMsg string) (
	ErrPrefixDto,
	error)

CopyOut - Creates a deep copy of the data fields contained in the current ErrPrefixDto instance, and returns that data as a new instance of ErrPrefixDto.

------------------------------------------------------------------------

Input Parameters 

eMsg                string
   - This is an error prefix which is included in all returned
     error messages. Usually, it contains the names of the calling
     method or methods. Note: Be sure to leave a space at the end
     of 'eMsg'.

------------------------------------------------------------------------

Return Values 

ErrPrefixDto
   - If this method completes successfully, a deep copy of the
     current ErrPrefixDto instance will be returned through
     this parameter as a completely new instance of
     ErrPrefixDto.

error
   - If this method completes successfully, the returned error Type
     is set to 'nil'. If errors are encountered during processing,
     the returned error Type will encapsulate an error message.
     Note that this error message will incorporate the method
     chain and text passed by input parameter, 'eMsg'. The
     'eMsg' text will be prefixed to the beginning of the returned
     error message.

func (*ErrPrefixDto) CopyOutToIBuilder added in v1.6.0 

func (ePrefDto *ErrPrefixDto) CopyOutToIBuilder(
	inComingIBuilder IBuilderErrorPrefix)

CopyOutToIBuilder - Receives an object implementing the IBuilderErrorPrefix Interface and populates that object with the error prefix and error context information contained in the current ErrPrefixDto instance.

This method will transfer error prefix and context information OUT to object implementing the IBuilderErrorPrefix interface.

----------------------------------------------------------------

Input Parameters 

inComingIBuilder    IBuilderErrorPrefix
   - Any object which implements the IBuilderErrorPrefix
     interface.

-----------------------------------------------------------------

Return Values 

--- NONE ---

func (*ErrPrefixDto) CopyPtr added in v1.4.0 

func (ePrefDto *ErrPrefixDto) CopyPtr() *ErrPrefixDto

CopyPtr - Creates a deep copy of the data fields contained in the current ErrPrefixDto instance, and returns that data as a pointer to a new instance of ErrPrefixDto.

------------------------------------------------------------------------

Input Parameters 

--- NONE ---

------------------------------------------------------------------------

Return Values 

*ErrPrefixDto
   - If this method completes successfully, a deep copy of the
     current ErrPrefixDto instance will be returned through
     this parameter as a pointer to a new instance of
     ErrPrefixDto.

func (*ErrPrefixDto) DeleteLastErrPrefix added in v1.7.0 

func (ePrefDto *ErrPrefixDto) DeleteLastErrPrefix() (
	isCollectionEmpty bool)

DeleteLastErrPrefix - Deletes the last Error Prefix Information object in the collection maintained by this ErrPrefixDto instance.

After the deletion operation is completed, this method returns a boolean value indicating whether the remaining collection of Error Prefix Information objects is empty.

Deleting the Error Prefix Information object deletes both the error prefix and error context information elements.

To delete all Error Prefix Information objects in the collection, call ErrPrefixDto.EmptyEPrefCollection().

----------------------------------------------------------------

Input Parameters 

--- NONE ---

------------------------------------------------------------------------

Return Values 

isCollectionEmpty   bool
   - After this method completes the deletion of the Last Error
     Prefix Information object in the current ErrPrefixDto, it
     will set this to boolean return value to signal whether
     remaining collection of Error Prefix Information objects
     is empty. An empty collection means it contains zero
     objects.

func (*ErrPrefixDto) Empty added in v1.6.0 

func (ePrefDto *ErrPrefixDto) Empty()

Empty - Reinitializes all internal member variables for the current ErrPrefixDto instance to their zero values. This method will effectively delete all error prefix information contained in the current ErrPrefixDto instance.

IMPORTANT All existing error prefix and error context information in this ErrPrefixDto instance will be overwritten and deleted.

func (*ErrPrefixDto) EmptyEPrefCollection 

func (ePrefDto *ErrPrefixDto) EmptyEPrefCollection()

EmptyEPrefCollection - All instances of ErrPrefixDto store error prefix information internally in an array of ErrorPrefixInfo objects. This method will delete or empty the ErrorPrefixInfo array for the current ErrPrefixDto instance and initialize it to nil.

IMPORTANT Effectively, this will delete all existing error prefix information stored in the current ErrPrefixDto instance.

func (*ErrPrefixDto) Equal 

func (ePrefDto *ErrPrefixDto) Equal(
	ePrefixDto2 *ErrPrefixDto) bool

Equal - Returns a boolean flag signaling whether the data values contained in the current ErrPrefixDto instance are equal to those contained in input parameter, 'ePrefixDto2'

------------------------------------------------------------------------

Input Parameters 

ePrefixDto2         *ErrPrefixDto
   - A pointer to an instance of ErrPrefixDto. The data values
     contained in this instance will be compared to those
     contained in the current ErrPrefixDto instance (ePrefDto)
     to determine equality.

------------------------------------------------------------------------

Return Values 

bool
   - A boolean flag signaling whether the data values contained
     in the current ErrPrefixDto instance are equal to those
     contained in input parameter 'ePrefixDto2'. If the data
     values are equal in all respects, this returned boolean
     value will be set to 'true'.

func (*ErrPrefixDto) GetEPrefCollection 

func (ePrefDto *ErrPrefixDto) GetEPrefCollection() []ErrorPrefixInfo

GetEPrefCollection - Returns a deep copy of the current error prefix collection maintained by this ErrPrefixDto instance.

func (*ErrPrefixDto) GetEPrefCollectionLen 

func (ePrefDto *ErrPrefixDto) GetEPrefCollectionLen() int

GetEPrefCollectionLen - Returns the number of elements in the error prefix array. Effectively this is a count of the number of error prefix elements maintained by this ErrPrefixDto instance.

----------------------------------------------------------------

Input Parameters 

--- NONE ---

-----------------------------------------------------------------

Return Values 

int
   - This integer value represents the number of separate error
     prefix elements maintained by this ErrPrefixDto instance.

func (*ErrPrefixDto) GetEPrefStrings added in v1.5.0 

func (ePrefDto *ErrPrefixDto) GetEPrefStrings() [][2]string

GetEPrefStrings - Returns a two dimensional slice of Error Prefix and Context strings.

The Error Prefix is always in the [x][0] position. The Error Context string is always in the [x][1] position. The Error Context string may be an empty string.

func (*ErrPrefixDto) GetInputStringDelimiters added in v1.6.0 

func (ePrefDto *ErrPrefixDto) GetInputStringDelimiters() ErrPrefixDelimiters

GetInputStringDelimiters - Returns the input string delimiters configured for the current instance of ErrPrefixDto.

Input string delimiters are applied the current ErrPrefixDto instance receives and parses raw strings containing error prefix information. Such strings are parsed before extracting error prefix information for internal storage in the error prefix collection maintained by the current ErrPrefixDto instance.

If input string delimiters were not directly configured by the user, the default input string delimiters will be applied.

The default input string delimiters are listed as follows: 

New Line Error Prefix Delimiter = "\n"
In-Line Error Prefix Delimiter  = " - "
New Line Error Context Delimiter = "\n :  "
In-Line Error Context Delimiter = " : "

To set and control input string delimiters use method: 

ErrPrefixDto.SetInputStringDelimiters()

func (*ErrPrefixDto) GetIsLastLineTerminatedWithNewLine 

func (ePrefDto *ErrPrefixDto) GetIsLastLineTerminatedWithNewLine() bool

GetIsLastLineTerminatedWithNewLine - Returns the boolean flag which determines whether the last line of error prefix strings returned by this ErrPrefixDto instance will be terminated with a new line character ('\n').

By default, the last line of error prefix strings returned by the method 'ErrPrefixDto.String()' DO NOT end with a new line character ('\n'). In other words, the last line of returned error prefix strings ARE NOT, by default, terminated with new line characters ('\n').

If terminating the last line of error prefix strings with a new line character ('\n') is a preferred option, use the method 'SetIsLastLineTermWithNewLine()' to configure this feature.

----------------------------------------------------------------

Input Parameters 

--- NONE ---

-----------------------------------------------------------------

Return Values 

bool
   - If this return parameter is set to 'true', it signals that
     the last line of all error prefix strings returned by this
     ErrPrefixDto instance WILL BE terminated with a new line
     character ('\n').

func (*ErrPrefixDto) GetLastErrPrefix added in v1.7.0 

func (ePrefDto *ErrPrefixDto) GetLastErrPrefix(
	eMsg string) (
	errPrefInfo ErrorPrefixInfo,
	collectionIsEmpty bool,
	err error)

GetLastErrPrefix - Returns a deep copy of the last Error Prefix Information object in the Error Prefix collection maintained by the current ErrPrefixDto instance.

----------------------------------------------------------------

Input Parameters 

eMsg                string
   - This is an error prefix which is included in all returned
     error messages returned by this method. Usually, it
     contains the names of the calling method or methods.

     Note: Be sure to leave a space at the end of 'eMsg'.
     This parameter is optional.

------------------------------------------------------------------------

Return Values 

errPrefInfo         ErrorPrefixInfo
   - If this method completes successfully, a deep copy of the
     last Error Prefix Information object in the current
     ErrPrefixDto collection will be returned in this
     parameter.

collectionIsEmpty   bool
   - If the current Error Prefix Information collection
     maintained by the current ErrPrefixDto instance is empty,
     this returned boolean value will be set to 'true'. A
     return value of 'true' also signals that the returned
     'errPrefInfo' parameter described above is empty and
     invalid.

err                 error
   - If this method completes successfully, the returned error Type
     is set to 'nil'. If errors are encountered during processing,
     the returned error Type will encapsulate an error message.
     Note that this error message will incorporate the method
     chain and text passed by input parameter, 'eMsg'.

func (*ErrPrefixDto) GetLeadingTextStr added in v1.7.0 

func (ePrefDto *ErrPrefixDto) GetLeadingTextStr() string

GetLeadingTextStr - Returns the current value of the leading text string. This value is stored internally in the member variable, 'leadingTextStr'.

The leading text string is a string supplied by the user which is stored in the current instance of ErrPrefixDto. It is used to add a string of text characters to the beginning of formatted error prefix text output for display purposes.

When the output methods ErrPrefixDto.StrMaxLineLen() or ErrPrefixDto.String() are called to display error prefix information, the leading text string will be appended to the beginning of that error prefix text display.

The value of the leading text string is set by calling the method, ErrPrefixDto.SetLeadingTextStr().

The default for the leading text string is a zero length or empty string.

func (*ErrPrefixDto) GetLeftMarginChar added in v1.6.0 

func (ePrefDto *ErrPrefixDto) GetLeftMarginChar() rune

GetLeftMarginChar - Returns a rune or text character which will be used to populate the left margin of formatted error prefix strings returned by method ErrPrefixDto.String().

The default for the Left Margin Character is the space character (' '). This means that a value of zero for the Left Margin character will cause a space character to be used in populating the left margin for error prefix strings.

To set the Left Margin Character see method: ErrPrefixDto.SetLeftMarginChar().

Finally, remember that the Left Margin will never be applied to error prefix strings unless the the Left Margin Length parameter is greater than zero. To set the Left Margin Length, see method: ErrPrefixDto.SetLeftMarginLength().

func (*ErrPrefixDto) GetLeftMarginLength added in v1.6.0 

func (ePrefDto *ErrPrefixDto) GetLeftMarginLength() int

GetLeftMarginLength - Returns an integer value defining the length of the left margin which will be applied to formatted error prefix strings returned by method ErrPrefixDto.String().

If the length of the Left Margin is set to zero, no left margin will applied to error prefix strings returned by method ErrPrefixDto.String().

func (*ErrPrefixDto) GetMaxTextLineLen added in v1.6.0 

func (ePrefDto *ErrPrefixDto) GetMaxTextLineLen() uint

GetMaxTextLineLen - Returns the Maximum Error Prefix Line Length value for the current ErrPrefixDto instance.

The Maximum Error Prefix Line Length is the maximum number of characters allowed in a single line of error prefix information output for display purposes.

The returned unsigned integer value returned by this method controls the maximum line length character limit for this specific ErrPrefixDto instance. This maximum limit will remain in force for the life of this ErrPrefixDto instance or until a call is made to the method ErrPrefixDto.SetMaxTextLineLen() which is used to manage and change this value.

----------------------------------------------------------------

Input Parameters 

--- NONE ---

-----------------------------------------------------------------

Return Values 

uint
   - This unsigned integer specifies the maximum limit on the
     number of characters allowed in an error prefix text line
     output for display purposes.

func (*ErrPrefixDto) GetMaxTextLineLenDefault added in v1.6.0 

func (ePrefDto *ErrPrefixDto) GetMaxTextLineLenDefault() uint

GetMaxTextLineLenDefault - Returns the system default value for Maximum Text Line Length Limit.

The Maximum Text Line Length Limit is the number of characters allowed in an error prefix text line output for display purposes.

This system default value is provided for information purposes only. The system default value may or may not be applied to the current ErrPrefixDto instance. To learn the Maximum Text Line Length Limit applied to the current ErrPrefixDto instance, call method: ErrPrefixDto.GetMaxTextLineLen()

----------------------------------------------------------------

Input Parameters 

--- NONE ---

-----------------------------------------------------------------

Return Values 

uint
   - This unsigned integer specifies the system default value
     for the Maximum Text Line Length Limit. This value is
     provided for informational purposes only. The system
     default value may or may not be applied to the current
     ErrPrefixDto instance. To learn the Maximum Text Line
     Length Limit applied to the current ErrPrefixDto instance,
     call method:  ErrPrefixDto.GetMaxTextLineLen()

func (*ErrPrefixDto) GetOutputStringDelimiters added in v1.6.0 

func (ePrefDto *ErrPrefixDto) GetOutputStringDelimiters() ErrPrefixDelimiters

GetOutputStringDelimiters - Returns the output string delimiters configured for the current instance of ErrPrefixDto.

The output string delimiters are used to format error prefix and context information returned as strings by methods: 

ErrPrefixDto.String()
ErrPrefixDto.StrMaxLineLen()

Error prefix and context elements in these formatted, returned strings are separated by these output string delimiters.

If output string delimiters were not directly configured by the user, the default output string delimiters will be applied.

The default output string delimiters are listed as follows: 

New Line Error Prefix Delimiter = "\n"
In-Line Error Prefix Delimiter  = " - "
New Line Error Context Delimiter = "\n :  "
In-Line Error Context Delimiter = " : "

To set and control output string delimiters use method: 

ErrPrefixDto.SetOutputStringDelimiters()

func (*ErrPrefixDto) GetStrDelimiters added in v1.6.0 

func (ePrefDto *ErrPrefixDto) GetStrDelimiters() (
	inputStrDelimiters ErrPrefixDelimiters,
	outputStrDelimiters ErrPrefixDelimiters)

GetStrDelimiters - Returns two ErrPrefixDelimiters objects which containing the input string delimiters and the output string delimiters configured for the current instance of ErrPrefixDto.

Input string delimiters are employed by the current ErrPrefixDto instance when receiving and parsing raw strings containing error prefix information. Such strings are parsed before extracting error prefix information to be stored in the error prefix collection maintained by the current ErrPrefixDto instance.

Output string delimiters on the other hand are used by the current ErrPrefixDto instance to format error prefix strings for output. Formatted strings returned for output are generated by the following two methods: 

ErrPrefixDto.String()
ErrPrefixDto.StrMaxLineLen()

If the input and output string delimiters were not directly configured by the user, the system default string delimiters will be applied. The system default string delimiters are listed as follows: 

New Line Error Prefix Delimiter = "\n"
In-Line Error Prefix Delimiter  = " - "
New Line Error Context Delimiter = "\n :  "
In-Line Error Context Delimiter = " : "

func (*ErrPrefixDto) GetTrailingTextStr added in v1.7.0 

func (ePrefDto *ErrPrefixDto) GetTrailingTextStr() string

GetTrailingTextStr - Returns the current value of the trailing text string. This value is stored internally in the member variable, 'trailingTextStr'.

The trailing text string is a string supplied by the user which is stored in the current instance of ErrPrefixDto. It is used to append a string of text characters to the end of formatted error prefix text output for display purposes.

When the output methods ErrPrefixDto.StrMaxLineLen() or ErrPrefixDto.String() are called to display error prefix information, the trailing text string will be appended to the end of that error prefix text display.

The value of the trailing text string is set by calling the method, ErrPrefixDto.SetTrailingTextStr().

The default for the trailing text string is a zero length or empty string.

func (*ErrPrefixDto) GetTurnOffTextDisplay added in v1.6.0 

func (ePrefDto *ErrPrefixDto) GetTurnOffTextDisplay() bool

GetTurnOffTextDisplay - Returns the current value of the "Turn Off Text Display" flag represented by internal member variable: 

ErrPrefixDto.turnOffTextDisplay

If this flag ('turnOffTextDisplay') is set to 'true', this instance of ErrPrefixDto WILL NOT format and return error prefix and context information through method, ErrPrefixDto.String(). In this case, the method ErrPrefixDto.String() will instead return an empty string.

Conversely, if this flag ('turnOffTextDisplay') is set to 'false' formatted error prefix and context information WILL BE formatted and returned through method ErrPrefixDto.String().

To control the status of the "Turn Off Text Display" flag, see method ErrPrefixDto.SetTurnOffTextDisplay().

func (*ErrPrefixDto) IsValidInstance added in v1.6.0 

func (ePrefDto *ErrPrefixDto) IsValidInstance() bool

IsValidInstance - Returns a boolean flag signalling whether the current ErrPrefixDto instance is valid, or not.

If this method returns a boolean value of 'false', it signals that the current ErrPrefixDto instance is invalid.

If this method returns a boolean value of 'true', it signals that the current ErrPrefixDto instance is valid in all respects.

----------------------------------------------------------------

Input Parameters 

--- NONE ---

-----------------------------------------------------------------

Return Values 

bool
   - This boolean flag signals whether the current
     ErrPrefixDto instance is valid.

     If this method returns a value of 'false', it signals that
     the current ErrPrefixDto instance is invalid.

     If this method returns a value of 'true', it signals that
     the current ErrPrefixDto instance is valid in all
     respects.

func (*ErrPrefixDto) IsValidInstanceError added in v1.6.0 

func (ePrefDto *ErrPrefixDto) IsValidInstanceError(
	ePrefix string) error

IsValidInstanceError - Returns an error type signalling whether the current ErrPrefixDto instance is valid, or not.

If this method returns an error value NOT equal to 'nil', it signals that the current ErrPrefixDto instance is invalid.

If this method returns an error value which IS equal to 'nil', it signals that the current ErrPrefixDto instance is valid in all respects.

----------------------------------------------------------------

Input Parameters 

ePrefix             string
   - This is an error prefix which is included in all returned
     error messages. Usually, it contains the names of the calling
     method or methods. Note: Be sure to leave a space at the end
     of 'ePrefix'.

-----------------------------------------------------------------

Return Values 

error
   - If this returned error type is set equal to 'nil', it
     signals that the current ErrPrefixDto is valid in all
     respects.

     If this returned error type is NOT equal to 'nil', it
     signals that the current ErrPrefixDto is invalid.

func (*ErrPrefixDto) MergeErrPrefixDto 

func (ePrefDto *ErrPrefixDto) MergeErrPrefixDto(
	incomingErrPrefixDto *ErrPrefixDto)

MergeErrPrefixDto - Receives a pointer to another ErrPrefixDto object and proceeds to add the error prefix collection to that of the current ErrPrefixDto instance.

This means that the error prefix collection for 'incomingErrPrefixDto' will be added to the end of the collection for the current ErrPrefixDto instance.

func (ErrPrefixDto) New 

func (ePrefDto ErrPrefixDto) New() ErrPrefixDto

New - Returns a new and properly initialized instance of ErrPrefixDto. String delimiters are set to the system defaults.

----------------------------------------------------------------

Input Parameters 

-- NONE --

-----------------------------------------------------------------

Return Values 

ErrPrefixDto
   - This method will return a new, properly initialized
     instance of ErrPrefixDto. The ErrorPrefixInfo collection
     encapsulated by the new instance will be an empty
     collection containing zero elements.

func (ErrPrefixDto) NewEPrefCollection 

func (ePrefDto ErrPrefixDto) NewEPrefCollection(
	errorPrefixCollection string) (
	numberOfCollectionItemsParsed int,
	newErrPrefixDto ErrPrefixDto)

NewEPrefCollection - Returns a new and properly initialized instance of ErrPrefixDto. This method receives a string containing one or more error prefix and error context pairs. This error prefix information is parsed and stored internally as individual error prefix elements.

Upon completion this method returns an integer value identifying the number of error prefix elements successfully parsed and stored for future use.

String delimiters are set to the system defaults.

----------------------------------------------------------------

Input Parameters 

errorPrefixCollection         string
   - A string consisting of a series of error prefix strings.
     Error prefixes should be delimited by either a new line
     character ('\n') or the in-line delimiter string, " - ".

     If the collection string contains error context strings
     as well, they should be delimited with either a new line
     delimiter string, "\n :  " or an in-line delimiter string,
     " : ".

-----------------------------------------------------------------

Return Values 

numberOfCollectionItemsParsed int
   - This returned integer value contains the number of error
     prefix elements parsed from input parameter
     'errorPrefixCollection' and stored internally for future
     use.

newErrPrefixDto               ErrPrefixDto
   - This method will return a newly created instance of
     ErrPrefixDto configured with the error prefix information
     parsed from input parameter, 'errorPrefixCollection'.

func (ErrPrefixDto) NewEPrefCtx added in v1.5.2 

func (ePrefDto ErrPrefixDto) NewEPrefCtx(
	newErrPrefix string,
	newErrContext string) ErrPrefixDto

NewEPrefCtx - Returns a new and properly initialized instance of ErrPrefixDto. The returned ErrPrefixDto instance will be configured with error prefix information extracted from input parameter, 'newErrPrefix'. Optional error context information is extracted from input parameter, 'newErrContext'.

Error prefix text is designed to be configured at the beginning of error messages and is most often used to document the thread of code execution by listing the calling sequence for a specific list of functions and methods.

The error context string is designed to provide additional information about the function or method identified by the associated error prefix string. Typical context information might include variable names, variable values and additional details on function execution.

String delimiters are set to the system defaults.

----------------------------------------------------------------

Input Parameters 

newErrPrefix        string
   - The new error prefix string typically identifies the
     function or method which is currently executing. This
     information is used to document source code execution flow
     in error messages.

     This method is designed to process a single new error prefix
     string. To process a collection of error prefix strings, see
     method 'ErrPrefixDto.NewEPrefOld()'.

newErrContext       string
   - This is the error context information associated with the
     new error prefix string ('newErrPrefix'). This parameter
     is optional and will accept an empty string.

-----------------------------------------------------------------

Return Values 

ErrPrefixDto
   - This method will return a new, properly initialized
     instance of ErrPrefixDto containing error prefix
     information extracted from input parameters,
     'newErrPrefix' and 'newErrContext'.

func (ErrPrefixDto) NewEPrefOld 

func (ePrefDto ErrPrefixDto) NewEPrefOld(
	oldErrPrefix string) ErrPrefixDto

NewEPrefOld - Returns a new and properly initialized instance of ErrPrefixDto. The returned ErrPrefixDto instance will be configured with error prefix information extracted from input parameter, 'oldErrPrefix'.

Error prefix text is designed to be configured at the beginning of error messages and is most often used to document the thread of code execution by listing the calling sequence for a specific list of functions and methods.

The error context string is designed to provide additional information about the function or method identified by the associated error prefix string. Typical context information might include variable names, variable values and additional details on function execution.

This method is designed to process a series of error prefix strings passed through input parameter, 'oldErrPrefix'. If only one error prefix string is available, consider using method 'ErrPrefixDto.NewEPrefCtx()'.

String delimiters are set to the system defaults.

----------------------------------------------------------------

Input Parameters 

oldErrPrefix        string
   - This includes the previous or preexisting error prefix
     string which will encapsulate one or more error prefix
     elements. This string will be parsed into error prefix and
     error context components and stored in the returned
     ErrPrefixDto instance.

     This string should consist of a series of error prefix
     strings. Error prefixes should be delimited by either a
     new line character ('\n') or the in-line delimiter string,
     " - ".

     If this string contains associated error context strings
     as well, they should be delimited with either a new line
     delimiter string, "\n :  " or an in-line delimiter string,
     " : ".

-----------------------------------------------------------------

Return Values 

ErrPrefixDto
   - This method will return a new, properly initialized
     instance of ErrPrefixDto containing error prefix
     information extracted from input parameter,
     'oldErrPrefix'.

func (ErrPrefixDto) NewFromErrPrefDto added in v1.7.0 

func (ePrefDto ErrPrefixDto) NewFromErrPrefDto(
	dto *ErrPrefixDto,
	newErrPrefix string,
	newErrContext string) (
	newErrPrefDto *ErrPrefixDto,
	err error)

NewFromErrPrefDto - Receives a pointer to an instance of ErrPrefixDto, a new error prefix string and a new error context string. The method then proceeds to merge these three elements into a new instance of ErrPrefixDto.

The new returned instance is configured as a pointer to the new ErrPrefixDto instance.

If the pointer to the ErrPrefixDto input parameter is nil, this method will not return an error. Instead the new returned instance of ErrPrefixDto will include on the 'newErrPrefix' and 'newErrContext' values.

If the pointer to the ErrPrefixDto input parameter is not nil but contains invalid values, this method will return an error.

If the pointer to the ErrPrefixDto input parameter is nil and input parameter 'newErrPrefix' is an empty string, this method will return an error.

----------------------------------------------------------------

Input Parameters 

dto                 *ErrPrefixDto
   - An instance of ErrPrefixDto which will be merged with
     input parameters 'newErrPrefix' and 'newErrContext'.

     If 'dto' is a nil value no error will be returned and the
     new returned instance of ErrPrefixDto will consist solely
     of input parameters 'newErrPrefix' and 'newErrContext'.

newErrPrefix        string
   - A new error prefix represents typically identifies the
     function or method which is currently executing. This
     information is used to document source code execution flow
     in error messages.

     This error prefix information will be added to the
     internal collection of error prefixes maintained by the
     new instance of ErrPrefixDto returned by this method.

     If this parameter is set to an empty string and input
     parameter 'dto' is a nil value, this method will return an
     error.

newErrContext       string
   - This is error context information associated with the new
     error prefix ('newErrPrefix') string described above.

     This parameter is optional and will accept an empty
     string.

-----------------------------------------------------------------

Return Values 

*ErrPrefixDto
   - If this method completes successfully, it will return a
     pointer to a new instance of ErrPrefixDto containing
     consolidated error prefix and error context information
     generated from input parameters 'dto, 'newErrPrefix',
     and 'newErrContext'.

error
   - If this method completes successfully, the returned error
     Type is set equal to 'nil'.

     If errors are encountered during processing, the returned
     error Type will encapsulate an error message.

     In the event of an error, the value of parameter
     'newErrPrefix' will be prefixed and attached to the
     beginning of the error message.

func (ErrPrefixDto) NewFromIErrorPrefix added in v1.3.0 

func (ePrefDto ErrPrefixDto) NewFromIErrorPrefix(
	iEPref IErrorPrefix) ErrPrefixDto

NewFromIErrorPrefix - Receives an object which implements the IErrorPrefix interface and returns a new, populated instance of ErrPrefixDto.

If the IErrorPrefix ErrorPrefixInfo collection is empty, this method will return an empty instance of ErrPrefixDto.

String delimiters are set to the system defaults.

----------------------------------------------------------------

Input Parameters 

iEPref              IErrorPrefix
   - An object which implements the IErrorPrefix interface.
     Information extracted from this object will be used to
     replicate error prefix information in a new instance of
     ErrPrefixDto.

-----------------------------------------------------------------

Return Values 

ErrPrefixDto
   - This method will return a instance of ErrPrefixDto
     containing a duplicate of error prefix information
     extracted from input parameter 'iEPref'.

func (ErrPrefixDto) NewFromStrings added in v1.6.0 

func (ePrefDto ErrPrefixDto) NewFromStrings(
	oldErrPrefix string,
	newErrPrefix string,
	newErrContext string,
	inputStrDelimiters ErrPrefixDelimiters,
	outputStrDelimiters ErrPrefixDelimiters,
	ePrefix string) (ErrPrefixDto, error)

NewFromStrings - Receives a series of string parameters and proceeds to generate an return a new, populated ErrPrefixDto instance. The string parameters include error prefix and associated error context information.

Error prefix text is designed to be configured at the beginning of error messages and is most often used to document the thread of code execution by listing the calling sequence for a specific list of functions and methods.

The error context string is designed to provide additional information about the function or method identified by the associated error prefix string. Typical context information might include variable names, variable values and additional details on function execution.

This version of the 'New' method allows the user to specify both the input and output string delimiters. Input string delimiters are used to parse the Old Error Prefix string, the New Error Prefix string and the associated New Error Context string. The output string delimiters will be used to parse and format presentation error prefix information returned by methods: 

ErrPrefixDto.String()
ErrPrefixDto.StrMaxLineLen()

If all three of the input parameter strings are passed as empty strings, this method will simply return an unpopulated instance of ErrPrefixDto configured with the input and output string delimiters passed by the calling function.

If either of the input or output string delimiter objects are judged as invalid, this method will return an error.

----------------------------------------------------------------

Input Parameters 

oldErrPrefix        string
   - This includes the previous or preexisting error prefix
     string which will encapsulate one or more error prefix
     elements. This string will be parsed into error prefix and
     error context components and stored in the returned
     ErrPrefixDto instance.

     This string will be parsed for error prefix and associated
     error context information based on the input string
     delimiters contained in input parameter,
     'inputStrDelimiters'.

     If this string contains associated error context strings
     as well, they will also be parsed using the same input
     string delimiters.

     This parameter is optional and will accept an empty string.

newErrPrefix               string
   - The new error prefix string typically identifies the
     function or method which is currently executing. This
     information is used to document source code execution flow
     in error messages.

     This parameter is optional and will accept an empty string.

newErrContext              string
   - This is the error context information associated with the
     new error prefix string ('newErrPrefix').

     This parameter is optional and will accept an empty string.

inputStrDelimiters         ErrPrefixDelimiters
   - Sets the string delimiters used by the current
     ErrPrefixDto instance when receiving and parsing raw
     strings containing error prefix information. Such strings
     are parsed in order to extract error prefix information
     for storage in the error prefix collection maintained by
     the current ErrPrefixDto instance.

     If input string delimiters were not directly configured
     by the user, the system default input string delimiters
     will be applied.

     The system default input string delimiters are listed as
     follows:

       New Line Error Prefix Delimiter = "\n"
       In-Line Error Prefix Delimiter  = " - "
       New Line Error Context Delimiter = "\n :  "
       In-Line Error Context Delimiter = " : "

     To monitor input string delimiters, use method:
           ErrPrefixDto.GetInputStringDelimiters()

     If this input parameter is judged to be invalid, an
     error will be returned.

outputStrDelimiters        ErrPrefixDelimiters
   - Sets the string delimiters used by the current
     ErrPrefixDto instance to format error prefix strings
     returned by methods:
            ErrPrefixDto.String()
            ErrPrefixDto.StrMaxLineLen()

     If the input parameter, 'outputStrDelimiters', is invalid,
     this/ method will return an error.

     If output string delimiters are not directly configured by
     the user, the default output string delimiters will be
     applied.

     The default output string delimiters are listed as
     follows:

       New Line Error Prefix Delimiter = "\n"
       In-Line Error Prefix Delimiter  = " - "
       New Line Error Context Delimiter = "\n :  "
       In-Line Error Context Delimiter = " : "

     To monitor output string delimiters, use method:
       ErrPrefixDto.GetOutputStringDelimiters()

     If this input parameter is judged to be invalid, an

ePrefix             string
   - This is an error prefix which is included in all returned
     error messages. Usually, it contains the names of the calling
     method or methods. Note: Be sure to leave a space at the end
     of 'ePrefix'. This parameter is optional.

------------------------------------------------------------------------

Return Values 

ErrPrefixDto
   - This method will return a new, properly initialized
     instance of ErrPrefixDto containing error prefix
     information extracted from input parameter strings,
     'oldErrPrefix', 'newErrPrefix' and 'newErrContext'.

error
   - If this method completes successfully, the returned error Type
     is set to 'nil'. If errors are encountered during processing,
     the returned error Type will encapsulate an error message.
     Note that this error message will incorporate the method
     chain and text passed by input parameter, 'ePrefix'.

func (ErrPrefixDto) NewIBasicErrorPrefix added in v1.5.0 

func (ePrefDto ErrPrefixDto) NewIBasicErrorPrefix(
	iEPref IBasicErrorPrefix,
	newErrPrefix string,
	newErrContext string) (
	*ErrPrefixDto,
	error)

NewIBasicErrorPrefix - Receives an object which implements the IBasicErrorPrefix interface and returns a new, populated instance of ErrPrefixDto.

String delimiters are set to the system defaults.

----------------------------------------------------------------

Input Parameters 

iEPref              IBasicErrorPrefix
   - An object which implements the IBasicErrorPrefix
     interface.

     This interface contains one method, 'GetEPrefStrings()'.
     This single method returns a two dimensional array of
     strings. Each 2-Dimensional array element holds a separate
     string for error prefix and error context.

     Information extracted from this object will be used to
     generate error prefix information in a new instance of
     ErrPrefixDto.

     Be advised, if 'iEPref' is nil, this method will return
     an error

newErrPrefix        string
   - A new error prefix represents typically identifies the
     function or method which is currently executing. This
     information is used to document source code execution flow
     in error messages.

     This error prefix information will be added to the
     internal collection of error prefixes maintained by the
     new instance of ErrPrefixDto returned by this method.

     If this parameter is set to an empty string, no additional
     error prefix information will be added to the returned
     instance of ErrPrefixDto.

newErrContext       string
   - This is error context information associated with the new
     error prefix ('newErrPrefix') string described above.

     This parameter is optional and will accept an empty
     string.

-----------------------------------------------------------------

Return Values 

*ErrPrefixDto
   - If this method completes successfully, it will return a
     pointer to a new instance of ErrPrefixDto containing a
     duplicate of error prefix and error context information
     extracted from input parameter 'iEPref' plus new error
     prefix information supplied by parameters, 'newErrPrefix'
     and 'newErrContext'.

error
   - If this method completes successfully, the returned error
     Type is set equal to 'nil'.

     If errors are encountered during processing, the returned
     error Type will encapsulate an error message.

     In the event of an error, the value of parameter
     'newErrPrefix' will be prefixed and attached to the
     beginning of the error message.

func (ErrPrefixDto) NewIEmpty added in v1.5.0 

func (ePrefDto ErrPrefixDto) NewIEmpty(
	iEPref interface{},
	newErrPrefix string,
	newErrContext string) (
	*ErrPrefixDto,
	error)

NewIEmpty - Receives an empty interface. If that empty interface is convertible to one of the 10-valid types listed below, this method then proceeds to create and return a pointer to a new instance of ErrPrefixDto.

String delimiters are set to the system defaults. To configure String delimiters use method: 

ErrPrefixDto.NewIEmptyWithDelimiters()

----------------------------------------------------------------

Input Parameters 

iEPref              interface{}
   - An empty interface containing one of the 10-valid types
     listed below. Any one of these valid types will generate
     valid error prefix and error context information.

     The error prefix and error context information for this
     new ErrPrefixDto object will be extracted from input
     parameter, 'iEPref'. 'iEPref' is an empty interface which
     must be convertible to one of the following valid types:

     1. nil               - A nil value is valid and generates an empty
                            collection of error prefix and error context
                            information.

     2. Stringer          - The Stringer interface from the 'fmt' package.
                            This interface has only one method:
                                 type Stringer interface {
                                    String() string
                                 }

     3. string            - A string containing error prefix information.

     4. []string          - A one-dimensional slice of strings containing
                            error prefix information.

     5. [][2]string       - A two-dimensional slice of strings
                            containing error prefix and error context
                            information.

     6. strings.Builder   - An instance of strings.Builder. Error prefix
                            information will be imported into the new
                            returned instance of ErrPrefixDto.

     7  *strings.Builder  - A pointer to an instance of strings.Builder.
                            Error prefix information will be imported into
                            the new returned instance of ErrPrefixDto.

     8. ErrPrefixDto      - An instance of ErrPrefixDto. The
                            ErrorPrefixInfo from this object will be
                            copied to the new returned instance of
                            ErrPrefixDto.

     9. *ErrPrefixDto     - A pointer to an instance of ErrPrefixDto.
                            ErrorPrefixInfo from this object will be
                            copied to 'errPrefDto'.

    10. IBasicErrorPrefix - An interface to a method generating
                            a two-dimensional slice of strings
                            containing error prefix and error
                            context information.

     Any types not listed above will be considered invalid and
     trigger the return of an error.

newErrPrefix        string
   - A new error prefix represents typically identifies the
     function or method which is currently executing. This
     information is used to document source code execution flow
     in error messages.

     This error prefix information will be added to the
     internal collection of error prefixes maintained by the
     new instance of ErrPrefixDto returned by this method.

     If this parameter is set to an empty string, no additional
     error prefix information will be added to the returned
     instance of ErrPrefixDto.

newErrContext       string
   - This is error context information associated with the new
     error prefix ('newErrPrefix') string described above.

     This parameter is optional and will accept an empty
     string.

-----------------------------------------------------------------

Return Values 

*ErrPrefixDto
   - If this method completes successfully, it will return a
     pointer to a new instance of ErrPrefixDto containing a
     duplicate of error prefix and error context information
     extracted from input parameter 'iEPref' plus new error
     prefix information supplied by parameters, 'newErrPrefix'
     and 'newErrContext'.

error
   - If this method completes successfully, the returned error
     Type is set equal to 'nil'.

     If errors are encountered during processing, the returned
     error Type will encapsulate an error message.

     In the event of an error, the value of parameter
     'newErrPrefix' will be prefixed and attached to the
     beginning of the error message.

func (ErrPrefixDto) NewIEmptyWithDelimiters added in v1.6.0 

func (ePrefDto ErrPrefixDto) NewIEmptyWithDelimiters(
	iEPref interface{},
	newErrPrefix string,
	newErrContext string,
	inputStrDelimiters ErrPrefixDelimiters,
	outputStrDelimiters ErrPrefixDelimiters,
	ePrefix string) (
	*ErrPrefixDto,
	error)

NewIEmptyWithDelimiters - Receives an empty interface. If that empty interface is convertible to one of the 10-valid types listed below, this method then proceeds to create and return a pointer to a new, fully populated, instance of ErrPrefixDto.

This method allows the user to set String Delimiters used to parse string values for incoming error prefix information.

----------------------------------------------------------------

Input Parameters 

iEPref              interface{}
   - An empty interface containing one of the 10-valid types
     listed below. Any one of these valid types will generate
     valid error prefix and error context information.

     The error prefix and error context information for this
     new ErrPrefixDto object will be extracted from input
     parameter, 'iEPref'. 'iEPref' is an empty interface which
     must be convertible to one of the following valid types:

     1. nil               - A nil value is valid and generates an empty
                            collection of error prefix and error context
                            information.

     2. Stringer          - The Stringer interface from the 'fmt' package.
                            This interface has only one method:
                                 type Stringer interface {
                                    String() string
                                 }

     3. string            - A string containing error prefix information.

     4. []string          - A one-dimensional slice of strings containing
                            error prefix information.

     5. [][2]string       - A two-dimensional slice of strings
                            containing error prefix and error context
                            information.

     6. strings.Builder   - An instance of strings.Builder. Error prefix
                            information will be imported into the new
                            returned instance of ErrPrefixDto.

     7  *strings.Builder  - A pointer to an instance of strings.Builder.
                            Error prefix information will be imported into
                            the new returned instance of ErrPrefixDto.

     8. ErrPrefixDto      - An instance of ErrPrefixDto. The
                            ErrorPrefixInfo from this object will be
                            copied to the new returned instance of
                            ErrPrefixDto.

     9. *ErrPrefixDto     - A pointer to an instance of ErrPrefixDto.
                            ErrorPrefixInfo from this object will be
                            copied to 'errPrefDto'.

    10. IBasicErrorPrefix - An interface to a method generating
                            a two-dimensional slice of strings
                            containing error prefix and error
                            context information.

     Any types not listed above will be considered invalid and
     trigger the return of an error.

newErrPrefix        string
   - A new error prefix represents typically identifies the
     function or method which is currently executing. This
     information is used to document source code execution flow
     in error messages.

     This error prefix information will be added to the
     internal collection of error prefixes maintained by the
     new instance of ErrPrefixDto returned by this method.

     If this parameter is set to an empty string, no additional
     error prefix information will be added to the returned
     instance of ErrPrefixDto.

newErrContext       string
   - This is error context information associated with the new
     error prefix ('newErrPrefix') string described above.

     This parameter is optional and will accept an empty
     string.

inputStrDelimiters         ErrPrefixDelimiters
   - Sets the string delimiters used by the current
     ErrPrefixDto instance when receiving and parsing raw
     strings containing error prefix information. Such strings
     are parsed in order to extract error prefix information
     for storage in the error prefix collection maintained by
     the current ErrPrefixDto instance.

     If input string delimiters were not directly configured
     by the user, the system default input string delimiters
     will be applied.

     The system default input string delimiters are listed as
     follows:

       New Line Error Prefix Delimiter = "\n"
       In-Line Error Prefix Delimiter  = " - "
       New Line Error Context Delimiter = "\n :  "
       In-Line Error Context Delimiter = " : "

       To monitor input string delimiters, use method:
           ErrPrefixDto.GetInputStringDelimiters()

     If this input parameter is judged to be invalid, an

outputStrDelimiters        ErrPrefixDelimiters
   - Sets the string delimiters used by the current
     ErrPrefixDto instance to format error prefix strings
     returned by methods:
            ErrPrefixDto.String()
            ErrPrefixDto.StrMaxLineLen()

     If the input parameter, 'outputStrDelimiters', is invalid,
     this/ method will return an error.

     If output string delimiters are not directly configured by
     the user, the default output string delimiters will be
     applied.

     The default output string delimiters are listed as
     follows:

       New Line Error Prefix Delimiter = "\n"
       In-Line Error Prefix Delimiter  = " - "
       New Line Error Context Delimiter = "\n :  "
       In-Line Error Context Delimiter = " : "

     To monitor output string delimiters, use method:
       ErrPrefixDto.GetOutputStringDelimiters()

     If this input parameter is judged to be invalid, an

ePrefix                    string
   - This is an error prefix which is included in all returned
     error messages. Usually, it contains the names of the calling
     method or methods. Note: Be sure to leave a space at the end
     of 'ePrefix'. This parameter is optional.

-----------------------------------------------------------------

Return Values 

*ErrPrefixDto
   - If this method completes successfully, it will return a
     pointer to a new instance of ErrPrefixDto containing a
     duplicate of error prefix and error context information
     extracted from input parameter 'iEPref' plus new error
     prefix information supplied by parameters, 'newErrPrefix'
     and 'newErrContext'.

error
   - If this method completes successfully, the returned error
     Type is set equal to 'nil'.

     If errors are encountered during processing, the returned
     error Type will encapsulate an error message.

     In the event of an error, the value of parameter 'ePrefix'
     will be prefixed and attached to the beginning of the
     error message.

func (ErrPrefixDto) Ptr added in v1.2.0 

func (ePrefDto ErrPrefixDto) Ptr() *ErrPrefixDto

Ptr - Returns a pointer to a new and properly initialized instance of ErrPrefixDto.

----------------------------------------------------------------

Input Parameters 

-- NONE --

-----------------------------------------------------------------

Return Values 

ErrPrefixDto
   - This method will return a pointer to a new and properly
     initialized instance of ErrPrefixDto.

func (*ErrPrefixDto) ReplaceLastErrPrefix added in v1.7.0 

func (ePrefDto *ErrPrefixDto) ReplaceLastErrPrefix(
	newErrPrefix string,
	newErrContext string,
	eMsg string) (
	err error)

ReplaceLastErrPrefix - This method deletes and replaces the Last Error Prefix Information object in the current ErrPrefixDto collection with new error prefix and error context information generated from input parameters 'newErrPrefix' and 'newErrContext'.

----------------------------------------------------------------

Input Parameters 

newErrPrefix        string
   - The new error prefix represents typically identifies
     the function or method which is currently executing. This
     information is used to document source code execution flow
     in error messages.

     This method is designed to process a single new error
     prefix string and therefore 'newErrPrefix' is a required
     parameter. If 'newErrPrefix' is passed as a zero length or
     empty string, this method will return an error.

newErrContext       string
   - This is the error context information associated with the
     new error prefix ('newErrPrefix'). This parameter is
     optional and will accept an empty string.

eMsg                string
   - This is an error prefix which is included in all returned
     error messages returned by this method. Usually, it
     contains the names of the calling method or methods.

     Note: Be sure to leave a space at the end of 'eMsg'.
     This parameter is optional.

-----------------------------------------------------------------

Return Values 

err                 error
   - If this method completes successfully, the returned error Type
     is set to 'nil'. If errors are encountered during processing,
     the returned error Type will encapsulate an error message.
     Note that this error message will incorporate the method
     chain and text passed by input parameter, 'eMsg'.

func (*ErrPrefixDto) SetCtx 

func (ePrefDto *ErrPrefixDto) SetCtx(
	newErrContext string)

SetCtx - Sets or resets the error context for the last error prefix. This operation either adds, or replaces, the error context string associated with the last error prefix the current list of error prefixes maintained by this instance.

If the last error prefix already has an error context string, it will be replaced by input parameter, 'newErrContext'.

If the last error prefix does NOT have an associated error context, this new error context string will be associated with that error prefix.

If the internal list of error prefixes is currently empty, this method will take no action and exit.

If the input parameter string 'newErrContext' is 'empty' (zero length string), this method will delete the last error context associated with the last error prefix in the error prefix collection.

----------------------------------------------------------------

Input Parameters 

newErrContext       string
   - This string holds the new error context information. If
     the last error prefix in internal storage already has an
     associated error context, that context will be deleted and
     replaced by 'newErrContext'. If, however, the last error
     prefix does NOT have an associated error context, this
     'newErrContext' string will be added and associated with
     that last error prefix.

     If this string is 'empty' (zero length string), this
     method will delete the last error context associated with
     the last error prefix in the error prefix collection.

-----------------------------------------------------------------

Return Values 

--- NONE ---

func (*ErrPrefixDto) SetCtxEmpty added in v1.3.0 

func (ePrefDto *ErrPrefixDto) SetCtxEmpty()

SetCtxEmpty - Deletes the last error context for the last error prefix in this instance of ErrPrefixDto.

----------------------------------------------------------------

Input Parameters 

--- NONE ---

-----------------------------------------------------------------

Return Values 

--- NONE ---

func (*ErrPrefixDto) SetEPref 

func (ePrefDto *ErrPrefixDto) SetEPref(
	newErrPrefix string)

SetEPref - Adds an error prefix string to the list of previous error prefix strings maintained by this instance of ErrPrefixDto.

The error prefix text is designed to be configured at the beginning of error messages and is most often used to document the thread of code execution by listing the calling sequence for specific functions and methods.

This method is designed to process a single error prefix string passed in input parameter 'newErrPrefix'. If this string contains multiple error prefixes, use method 'ErrPrefixDto.SetEPrefOld()'.

----------------------------------------------------------------

Input Parameters 

newErrPrefix        string
   - The new error prefix represents typically identifies
     the function or method which is currently executing. This
     information is used to document source code execution flow
     in error messages.

     This new error prefix will be added to the internal list
     of error prefixes maintained by this ErrPrefixDto
     instance.

-----------------------------------------------------------------

Return Values 

--- NONE ---

func (*ErrPrefixDto) SetEPrefCollection 

func (ePrefDto *ErrPrefixDto) SetEPrefCollection(
	newEPrefCollection []ErrorPrefixInfo)

func (*ErrPrefixDto) SetEPrefCtx 

func (ePrefDto *ErrPrefixDto) SetEPrefCtx(
	newErrPrefix string,
	newErrContext string)

SetEPrefCtx - Adds an error prefix and an error context string to the list of previous error prefix/context information.

Error prefix text is designed to be configured at the beginning of error messages and is most often used to document the thread of code execution by listing the calling sequence for a specific list of functions and methods.

The error context string is designed to provide additional information about the function or method identified by the associated error prefix string. Typical context information might include variable names, variable values and additional details on function execution.

----------------------------------------------------------------

Input Parameters 

newErrPrefix        string
   - The new error prefix represents typically identifies
     the function or method which is currently executing. This
     information is used to document source code execution flow
     in error messages.

     This method is designed to process a single new error prefix
     string. To process a collection of error prefix strings, see
     method 'ErrPrefixDto.SetEPrefOld()'.

newErrContext       string
   - This is the error context information associated with the
     new error prefix ('newErrPrefix'). This parameter is
     optional and will accept an empty string.

-----------------------------------------------------------------

Return Values 

--- NONE ---

func (*ErrPrefixDto) SetEPrefOld 

func (ePrefDto *ErrPrefixDto) SetEPrefOld(
	oldErrPrefix string)

SetEPrefOld - Deletes the current error prefix information and initializes this ErrPrefixDto instance with an old or preexisting error prefix string. This error prefix string input parameter typically includes one or more error prefix elements and may also include associated error context elements. This string will be parsed and into individual error prefix and error context components and stored internally in the current ErrPrefixDto instance.

Error prefix text is designed to be configured at the beginning of error messages and is most often used to document the thread of code execution by listing the calling sequence for a specific list of functions and methods.

The error context string is designed to provide additional information about the function or method identified by the associated error prefix string. Typical context information might include variable names, variable values and additional details on function execution.

IMPORTANT All existing error prefix and error context information in this ErrPrefixDto instance will be overwritten and deleted.

----------------------------------------------------------------

Input Parameters 

oldErrPrefix        string
   - This includes the previous or preexisting error prefix
     string. This string will be parsed into error prefix
     and error context components and stored in the current
     ErrPrefixDto instance.

     This string should consist of a series of error prefix
     strings. Error prefixes should be delimited by either a
     new line character ('\n') or the in-line delimiter string,
     " - ".

     If this string contains associated error context strings
     as well, they should be delimited with either a new line
     delimiter string, "\n :  " or an in-line delimiter string,
     " : ".

-----------------------------------------------------------------

Return Values 

--- NONE ---

func (*ErrPrefixDto) SetEPrefStrings added in v1.5.0 

func (ePrefDto *ErrPrefixDto) SetEPrefStrings(
	twoDStrArray [][2]string)

SetEPrefStrings - This method first deletes all pre-existing error prefix and error context information and then replaces that information with new data extracted from the two-dimensional string array passed as an input parameter ('twoDStrArray').

This two-dimensional string array contains both error prefix and error context information. The Error Prefix string is always in the [x][0] position. The Error Context string is always in the [x][1] position. The Error Context string is optional and may be an empty string.

If input parameter 'twoDStrArray' is 'nil' or a zero length array, this method will take no action and exit.

To 'append' or 'add' a two-dimensional string array to existing error prefix information, see method: 

ErrPrefixDto.AddEPrefStrings()

IMPORTANT All existing error prefix and error context information in this ErrPrefixDto instance will be overwritten and deleted.

func (*ErrPrefixDto) SetIBasic added in v1.6.0 

func (ePrefDto *ErrPrefixDto) SetIBasic(
	incomingIBasic IBasicErrorPrefix,
	ePrefix string) error

SetIBasic - Deletes the current error prefix information and replaces it with new error prefix data passed to this method by an input parameter object implementing the IBasicErrorPrefix interface.

IMPORTANT All existing error prefix and error context information in this ErrPrefixDto instance will be overwritten and deleted.

----------------------------------------------------------------

Input Parameters 

incomingIBasic      IBasicErrorPrefix
   - An object implementing the IBasicErrorPrefix interface.
     Error prefix and context information will be generated
     from this object and used to overwrite and replace the
     existing error prefix and context information contained in
     the current ErrPrefixDto instance.

ePrefix             string
   - This is an error prefix which is included in all returned
     error messages returned by this method. Usually, it
     contains the names of the calling method or methods.

     Note: Be sure to leave a space at the end of 'eMsg'.
     This parameter is optional.

-----------------------------------------------------------------

Return Values 

error
   - If this method completes successfully, the returned error
     Type is set equal to 'nil'.

     If errors are encountered during processing, the returned
     error Type will encapsulate an error message.

     In the event of an error, the value of parameter 'ePrefix'
     will be prefixed and attached to the beginning of the
     error message.

func (*ErrPrefixDto) SetIBuilder added in v1.6.0 

func (ePrefDto *ErrPrefixDto) SetIBuilder(
	inComingIBuilder IBuilderErrorPrefix,
	callingMethodName string) error

SetIBuilder - Deletes the current error prefix information and replaces it with new error prefix data passed to this method by an input parameter object implementing the IBuilderErrorPrefix interface.

IMPORTANT All existing error prefix and error context information in this ErrPrefixDto instance will be overwritten and deleted.

----------------------------------------------------------------

Input Parameters 

inComingIBuilder    IBuilderErrorPrefix
   - An object implementing the IBuilderErrorPrefix interface.
     Error prefix and context information will be generated
     from this object and used to overwrite and replace the
     existing error prefix and context information contained in
     the current ErrPrefixDto instance.

callingMethodName   string
   - A string containing the name of the function which called
     this method. If an error occurs this string will be
     prefixed to the beginning of the returned error message.

     This parameter is optional. If an error prefix is not
     required, submit an empty string for this parameter ("").

-----------------------------------------------------------------

Return Values 

error
   - If this method completes successfully, the returned error
     Type is set equal to 'nil'.

     If errors are encountered during processing, the returned
     error Type will encapsulate an error message.

     In the event of an error, the value of parameter
     'callingMethodName' will be prefixed and attached to the
     beginning of the error message.

func (*ErrPrefixDto) SetIEmpty added in v1.6.0 

func (ePrefDto *ErrPrefixDto) SetIEmpty(
	iEPref interface{},
	callingMethodName string) error

SetIEmpty - Deletes the current error prefix information and replaces it with new error prefix data passed to this method through an empty interface.

IMPORTANT All existing error prefix and error context information in this ErrPrefixDto instance will be overwritten and deleted.

----------------------------------------------------------------

Input Parameters 

iEPref              interface{}
   - An empty interface containing one of the 10-valid types
     listed below. Any one of these valid types will generate
     valid error prefix and error context information. This
     error prefix data will then overwrite and replace that
     encapsulated in the current ErrPrefixDto instance.

     The error prefix and error context information for this
     new ErrPrefixDto object will be extracted from input
     parameter, 'iEPref'. 'iEPref' is an empty interface which
     must be convertible to one of the following valid types:

     1. nil               - A nil value is valid and generates an empty
                            collection of error prefix and error context
                            information.

     2. Stringer          - The Stringer interface from the 'fmt' package.
                            This interface has only one method:
                                 type Stringer interface {
                                    String() string
                                 }

     3. string            - A string containing error prefix information.

     4. []string          - A one-dimensional slice of strings containing
                            error prefix information.

     5. [][2]string       - A two-dimensional slice of strings
                            containing error prefix and error context
                            information.

     6. strings.Builder   - An instance of strings.Builder. Error prefix
                            information will be imported into the new
                            returned instance of ErrPrefixDto.

     7  *strings.Builder  - A pointer to an instance of strings.Builder.
                            Error prefix information will be imported into
                            the new returned instance of ErrPrefixDto.

     8. ErrPrefixDto      - An instance of ErrPrefixDto. The
                            ErrorPrefixInfo from this object will be
                            copied to the new returned instance of
                            ErrPrefixDto.

     9. *ErrPrefixDto     - A pointer to an instance of ErrPrefixDto.
                            ErrorPrefixInfo from this object will be
                            copied to 'errPrefDto'.

    10. IBasicErrorPrefix - An interface to a method generating
                            a two-dimensional slice of strings
                            containing error prefix and error
                            context information.

     Any types not listed above will be considered invalid and
     trigger the return of an error.

callingMethodName   string
   - A string containing the name of the function which called
     this method. If an error occurs this string will be
     prefixed to the beginning of the returned error message.

     This parameter is optional. If an error prefix is not
     required, submit an empty string for this parameter ("").

-----------------------------------------------------------------

Return Values 

error
   - If this method completes successfully, the returned error
     Type is set equal to 'nil'.

     If errors are encountered during processing, the returned
     error Type will encapsulate an error message.

     In the event of an error, the value of parameter
     'callingMethodName' will be prefixed and attached to the
     beginning of the error message.

func (*ErrPrefixDto) SetInputStringDelimiters added in v1.6.0 

func (ePrefDto *ErrPrefixDto) SetInputStringDelimiters(
	inputStrDelimiters ErrPrefixDelimiters,
	ePrefix string) error

SetInputStringDelimiters - Sets the string delimiters used by the current ErrPrefixDto instance when receiving and parsing raw strings containing error prefix information. Such strings are parsed in order to extract error prefix information for storage in the error prefix collection maintained by the current ErrPrefixDto instance.

If input string delimiters were not directly configured by the user, the system default input string delimiters will be applied.

The system default input string delimiters are listed as follows: 

New Line Error Prefix Delimiter = "\n"
In-Line Error Prefix Delimiter  = " - "
New Line Error Context Delimiter = "\n :  "
In-Line Error Context Delimiter = " : "

To monitor input string delimiters, use method: 

ErrPrefixDto.GetInputStringDelimiters()

To set and control output string delimiters, use method: 

ErrPrefixDto.SetOutputStringDelimiters()

func (*ErrPrefixDto) SetIsLastLineTermWithNewLine 

func (ePrefDto *ErrPrefixDto) SetIsLastLineTermWithNewLine(
	isLastLineTerminatedWithNewLine bool)

SetIsLastLineTermWithNewLine - By default, the last line of error prefix strings returned by the method ErrPrefixDto.String() ARE NOT terminated with a new line character ('\n'). In other words, by default, the last line of returned error prefix strings do not end with a new line character ('\n').

If the user prefers to terminate the last line of error prefix strings returned by this instance of ErrPrefixDto with a new line character ('\n'), the input parameter, 'isLastLineTerminatedWithNewLine', should be set to 'true'.

Error prefix strings are returned by calling method 'ErrPrefixDto.String()'.

----------------------------------------------------------------

Input Parameters 

isLastLineTerminatedWithNewLine    bool
   - If this parameter is set to 'true', the last line of all
     error prefix strings returned by this ErrPrefixDto
     instance WILL BE terminated with a new line character
     ('\n').

-----------------------------------------------------------------

Return Values 

--- NONE ---

func (*ErrPrefixDto) SetLeadingTextStr added in v1.7.0 

func (ePrefDto *ErrPrefixDto) SetLeadingTextStr(
	leadingTextStr string)

SetLeadingTextStr - Sets the internal member variable 'leadingTextStr'.

The leading text string is a string supplied by the user which is stored in the current instance of ErrPrefixDto. It is used to add a string of text characters to the beginning of formatted error prefix text displays.

When the output methods ErrPrefixDto.StrMaxLineLen() or ErrPrefixDto.String() are called to display error prefix information, the leading text string will be appended to the beginning of that error prefix text display.

The default for the leading text string is a zero length or empty string. To clear or reset the leading text string to an empty string, call this method, ErrPrefixDto.SetLeadingTextStr(), with an empty string or call the method ErrPrefixDto.ClearLeadingTextStr().

The leading text string can be used to add any combination of string characters to the beginning of an error prefix text display. Ideas for usage could include newline characters, dash lines ('-'), asterisk lines ('*'), equal lines ('-') or any other combination of text characters.

The leading text string is often used in conjunction with the trailing text string to highlight or separate error prefix information. The trailing text string is configured using method ErrPrefixDto.SetTrailingTextStr().

func (*ErrPrefixDto) SetLeftMarginChar added in v1.6.0 

func (ePrefDto *ErrPrefixDto) SetLeftMarginChar(
	leftMarginCharacter rune)

SetLeftMarginChar - Sets the character used in creating the left margin applied to all new lines generated in the error prefix string returned by method: ErrPrefixDto.String().

The default Left Margin Character is the empty space character (' '). Therefore, if the rune input parameter, 'leftMarginCharacter' is set to zero, it will default the Left Margin Character to an empty space value (' ').

Be Advised: If the Left Margin Length is set to zero, this character will never be used and the no left margin will be added to error prefix strings generated by method: ErrPrefixDto.String().

----------------------------------------------------------------

Input Parameters 

leftMarginCharacter rune
   - This character will be used to configure the left margin
     for error prefix strings returned by method
     ErrPrefixDto.String(). If this value is set to zero, it
     will engage the default Left Margin Character which is the
     empty space character (' ').

     If the Left Margin Length is set to zero, no left margin
     will be generated for error prefix strings and this
     character will never be used. Reference method
     ErrPrefixDto.SetLeftMarginLength().

-----------------------------------------------------------------

Return Values 

--- NONE ---

----------------------------------------------------------------

Example Usage

Example of Left Margin Character set to '*'. Left Margin Length set to 3. Maximum Line Length set to 40. Effective Maximum Line Length is 43. 

"***Tx1.Something() - Tx2.SomethingElse()   "
"***Tx3.DoSomething() - Tx4() - Tx5()       "
"***Tx6.DoSomethingElse()                   "
"***Tx7.TrySomethingNew()                   "
"*** :  something->newSomething             "
"***Tx8.TryAnyCombination()                 "
"***Tx9.TryAHammer() : x->y - Tx10.X()      "
"***Tx11.TryAnything() - Tx12.TryASalad()   "
"***Tx13.SomeFabulousAndComplexStuff()      "
"***Tx14.MoreAwesomeGoodness                "
"*** :  A=7 B=8 C=9                         "

func (*ErrPrefixDto) SetLeftMarginLength added in v1.6.0 

func (ePrefDto *ErrPrefixDto) SetLeftMarginLength(
	leftMarginLength int)

SetLeftMarginLength - Sets the length of the left margin applied to all new lines generated in the error prefix string returned by method: ErrPrefixDto.String()

The Left Margin Character can be set through method: 

ErrPrefixDto.SetLeftMarginChar()

If the Left Margin value is less than zero, this method will take no action and exit.

BE CAREFUL

This method will accept any 'leftMarginLength' greater than zero.

----------------------------------------------------------------

Input Parameters 

leftMarginLength    int
   - This value will be used to determine the length of the
     left margin configured in error prefix strings returned
     by method ErrPrefixDto.String().

     If this value is less than zero, this method will take no
     action and exit.

     Be advised, any left margin length greater than zer will
     be accepted.

-----------------------------------------------------------------

Return Values 

--- NONE ---

----------------------------------------------------------------

Example Usage

Example of Left Margin Length set to 3. Left Margin Character set to empty space ' '. Maximum Line Length set to 40. Effective Maximum Line Length is 43. 

"   Tx1.Something() - Tx2.SomethingElse()   "
"   Tx3.DoSomething() - Tx4() - Tx5()       "
"   Tx6.DoSomethingElse()                   "
"   Tx7.TrySomethingNew()                   "
"    :  something->newSomething             "
"   Tx8.TryAnyCombination()                 "
"   Tx9.TryAHammer() : x->y - Tx10.X()      "
"   Tx11.TryAnything() - Tx12.TryASalad()   "
"   Tx13.SomeFabulousAndComplexStuff()      "
"   Tx14.MoreAwesomeGoodness                "
"    :  A=7 B=8 C=9                         "

func (*ErrPrefixDto) SetMaxTextLineLen added in v1.2.0 

func (ePrefDto *ErrPrefixDto) SetMaxTextLineLen(
	maxErrPrefixTextLineLength int)

SetMaxTextLineLen - Sets the maximum limit on the number of characters allowed in an error prefix text line output for display purposes.

Setting this value will control the maximum character limit for this specific ErrPrefixDto instance. This maximum limit will remain in force for the life of this ErrPrefixDto instance or until another call is made to this method changing the value.

When this instance of ErrPrefixDto was initially created, a default value of 40-characters was applied.

----------------------------------------------------------------

Input Parameters 

maxErrPrefixTextLineLength      int
   - This unsigned integer value will be used to set the
     maximum number of characters allowed in a text display
     line for error prefix information.

     If 'maxErrPrefixTextLineLength' is set to a value less
     than ten (10) or to a value greater than one-million
     (1,000,000), the default value of 40-characters will be
     applied.

-----------------------------------------------------------------

Return Values 

--- NONE ---

func (*ErrPrefixDto) SetMaxTextLineLenToDefault added in v1.2.0 

func (ePrefDto *ErrPrefixDto) SetMaxTextLineLenToDefault()

SetMaxTextLineLenToDefault - Maximum Error Prefix Line Length is the maximum limit on the number of characters allowed in a single error prefix text line.

This method resets that maximum limit to its default value of 40-characters.

func (*ErrPrefixDto) SetOutputStringDelimiters added in v1.6.0 

func (ePrefDto *ErrPrefixDto) SetOutputStringDelimiters(
	outputStrDelimiters ErrPrefixDelimiters,
	ePrefix string) error

SetOutputStringDelimiters - Sets the string delimiters used by the current ErrPrefixDto instance to format error prefix strings returned by methods: 

ErrPrefixDto.String()
ErrPrefixDto.StrMaxLineLen()

If the input parameter, 'outputStrDelimiters', is invalid, this method will return an error.

If output string delimiters were not directly configured by the user, the default output string delimiters will be applied.

The default output string delimiters are listed as follows: 

New Line Error Prefix Delimiter = "\n"
In-Line Error Prefix Delimiter  = " - "
New Line Error Context Delimiter = "\n :  "
In-Line Error Context Delimiter = " : "

To monitor output string delimiters, use method: 

ErrPrefixDto.GetOutputStringDelimiters()

To set and control input string delimiters, use method: 

ErrPrefixDto.SetInputStringDelimiters()

func (*ErrPrefixDto) SetStrDelimitersToDefault added in v1.6.0 

func (ePrefDto *ErrPrefixDto) SetStrDelimitersToDefault()

SetStrDelimitersToDefault - Sets the Input String Delimiters and the Output String Delimiters to their system default values.

The ErrPrefixDto type maintains two types of string delimiters, Input String Delimiters and Output String Delimiters.

Input String Delimiters are used by ErrPrefixDto instances to parse raw string values containing error prefix and error context information received as input parameters from external sources. Methods performing this type of operation include but are not limited to: 

ErrPrefixDto.NewIEmptyWithDelimiters()
ErrPrefixDto.NewFromStrings()
ErrPrefixDto.NewEPrefOld()
ErrPrefixDto.SetEPrefOld()

Output String Delimiters are used by ErrPrefixDto instances to join or concatenate individual error prefix and error context components to form presentation text for output and use in preparation of error message strings. Methods performing this type of operation are: 

ErrPrefixDto.String()
ErrPrefixDto.StrMaxLineLen()

Initially, both the Input and Output System Delimiters for any given ErrPrefixDto instance are set to the system default values. This means that if the Input and Output String Delimiters were not directly configured by the user, the system default string delimiters are applied.

The system defaults for both Input and Output String Delimiters are listed as follows: 

New Line Error Prefix Delimiter = "\n"
In-Line Error Prefix Delimiter  = " - "
New Line Error Context Delimiter = "\n :  "
In-Line Error Context Delimiter = " : "

Users have the option of setting custom Input and Output String Delimiters using methods: 

ErrPrefixDto.SetOutputStringDelimiters()
ErrPrefixDto.SetInputStringDelimiters()

The current settings for String Delimiters can be monitored using methods: 

ErrPrefixDto.GetStrDelimiters()
ErrPrefixDto.GetInputStringDelimiters()
ErrPrefixDto.GetOutputStringDelimiters()

In the event it becomes necessary to reset the Input and Output String Delimiters to their original system default values, call this method.

func (*ErrPrefixDto) SetTrailingTextStr added in v1.7.0 

func (ePrefDto *ErrPrefixDto) SetTrailingTextStr(
	trailingTextStr string)

SetTrailingTextStr - Sets the internal member variable 'trailingTextStr'. The trailing text string is a string supplied by the user which is stored in the current instance of ErrPrefixDto.

When the output methods ErrPrefixDto.SetOutputStringDelimiters() or ErrPrefixDto.String() are called to display error prefix information, the trailing text string will be appended to the end of that error prefix text display.

The default for the trailing text string is a zero length or empty string. To clear or reset the trailing text string to an empty string, call this method, ErrPrefixDto.SetTrailingTextStr(), with an empty string or call the method ErrPrefixDto.ClearTrailingTextStr().

The trailing text string can be used to add any combination of string characters to the end of an error prefix text display. Ideas for usage could include newline characters ('\n'), dash lines ('-'), asterisk lines ('*'), equal lines ('-') or any other combination of text characters.

The trailing text string is often used in conjunction with the leading text string to highlight or separate error prefix information. The leading text string is configured using method ErrPrefixDto.SetLeadingTextStr().

func (*ErrPrefixDto) SetTurnOffTextDisplay added in v1.6.0 

func (ePrefDto *ErrPrefixDto) SetTurnOffTextDisplay(
	turnOffTextDisplay bool)

SetTurnOffTextDisplay - Controls the "Turn Off Text Display" flag represented by internal member variable: 

ErrPrefixDto.turnOffTextDisplay

If this flag (input parameter 'turnOffTextDisplay') is set to 'true', this instance of ErrPrefixDto WILL NOT format and return error prefix and context information through method, ErrPrefixDto.String(). In this case, the method ErrPrefixDto.String() will instead return an empty string.

Conversely, if this flag (input parameter 'turnOffTextDisplay') is set to 'false' formatted error prefix and context information WILL BE formatted and returned through method ErrPrefixDto.String().

To monitor the status of the "Turn Off Text Display" flag, see method ErrPrefixDto.GetTurnOffTextDisplay().

func (*ErrPrefixDto) StrMaxLineLen added in v1.2.0 

func (ePrefDto *ErrPrefixDto) StrMaxLineLen(
	maxLineLen int) string

StrMaxLineLen - Returns a formatted error prefix/context string incorporating all error prefix and error context information previously added to this ErrPrefixDto instance.

Error prefix information is stored internally in the 'ePrefCol' array.

Input parameter 'maxLineLen' is used to set the Maximum Text Line length Limit (in characters) for text returned by this method. If the value of 'maxLineLen' is less than 10, it will be discarded and the current Maximum Text Line Length Limit value will be used. If input parameter 'maxLineLen' is equal to or greater than 10, the Maximum Text Line Length Limit for this current ErrPrefixDto instance will be reset and configured to this new value.

If the "Turn Off Text Display Flag" is current set to 'true', this method will return an empty string. The default value for the "Turn Off Text Display Flag" is 'false'. To control the "Turn Off Text Display Flag" use method: 

ErrPrefixDto.SetTurnOffTextDisplay()

The error prefix string returned by this method will be formatted using output string delimiters previously configured for this instance of ErrPrefixDto.

If output string delimiters are invalid or were not directly configured by the user, the default output string delimiters will be applied.

The default output string delimiters are listed as follows: 

New Line Error Prefix Delimiter = "\n"
In-Line Error Prefix Delimiter  = " - "
New Line Error Context Delimiter = "\n :  "
In-Line Error Context Delimiter = " : "

To set and control output string delimiters use method: 

ErrPrefixDto.SetOutputStringDelimiters()

func (ErrPrefixDto) String 

func (ePrefDto ErrPrefixDto) String() string

String - Returns a formatted error prefix/context string incorporating all error prefixes previously added to this ErrPrefixDto instance.

Error prefix information is stored internally in the 'ErrPrefixDto.ePrefCol' array.

If the Left Margin has been set to a value greater than zero, that number of Left Margin Characters will be formatted in each new line of the returned error prefix string.

The Left Margin value can be set through method: 

ErrPrefixDto.SetLeftMarginLength()

The Left Margin Character can be set through method: 

ErrPrefixDto.SetLeftMarginChar()

The default Left Margin value is zero. The default Left Margin Character is the empty space character (' ').

Remember that configuring a left margin for the output error prefix string will extend the existing line length. So, if the maximum line length is set to 40 with a left margin length of 3, the effective maximum line length is 43.

The error prefix and context information returned by this method will be separated and formatted using previously configured output string delimiters. If these output string delimiters were not directly configured by the user, the default output string delimiters will be used.

The default output string delimiters are listed as follows: 

New Line Error Prefix Delimiter = "\n"
In-Line Error Prefix Delimiter  = " - "
New Line Error Context Delimiter = "\n :  "
In-Line Error Context Delimiter = " : "

To set and control output string delimiters, use method: 

ErrPrefixDto.SetOutputStringDelimiters()

If the Maximum Error Prefix Line Length value is less than 10-characters, this method will reset this value to the default of 40-characters. For more information, see the documentation for method: 

ErrPrefixDto.SetMaxTextLineLen()

func (*ErrPrefixDto) XCtx added in v1.1.0 

func (ePrefDto *ErrPrefixDto) XCtx(
	newErrContext string) *ErrPrefixDto

XCtx - Sets or resets the error context for the last error prefix. This operation either adds, or replaces, the error context string associated with the last error prefix the current list of error prefixes maintained by this instance.

This method is identical in function to ErrPrefixDto.SetCtx(). The only difference is that this method returns a pointer to the current ErrPrefixDto instance.

If the last error prefix already has an error context string, it will be replaced by input parameter, 'newErrContext'.

If the last error prefix does NOT have an associated error context, this new error context string will be associated with that error prefix.

If the internal list of error prefixes is currently empty, this method will take no action and exit.

If the input parameter string 'newErrContext' is 'empty' (zero length string), this method will delete the last error context associated with the last error prefix in the error prefix collection.

Be advised: The 'X' methods always return a pointer to current, modified, ErrPrefixDto instance.

----------------------------------------------------------------

Input Parameters 

newErrContext       string
   - This string holds the new error context information. If
     the last error prefix in internal storage already has an
     associated error context, that context will be deleted and
     replaced by 'newErrContext'. If, however, the last error
     prefix does NOT have an associated error context, this
     'newErrContext' string will be added and associated with
     that last error prefix.

     If this string is 'empty' (zero length string), this
     method will delete the last error context associated with
     the last error prefix in the error prefix collection.

-----------------------------------------------------------------

Return Values 

*ErrPrefixDto
   - Returns a pointer to the current ErrPrefixDto instance

func (*ErrPrefixDto) XCtxEmpty added in v1.3.0 

func (ePrefDto *ErrPrefixDto) XCtxEmpty() *ErrPrefixDto

XCtxEmpty - Deletes the last error context for the last error prefix in this instance of ErrPrefixDto

Be advised: The 'X' methods always return a pointer to current, modified, ErrPrefixDto instance.

----------------------------------------------------------------

Input Parameters 

--- NONE ---

-----------------------------------------------------------------

Return Values 

*ErrPrefixDto
   - Returns a pointer to the current ErrPrefixDto instance

func (*ErrPrefixDto) XEPref added in v1.1.0 

func (ePrefDto *ErrPrefixDto) XEPref(
	newErrPrefix string) *ErrPrefixDto

XEPref - Adds an error prefix string to the list of previous error prefix strings maintained by this instance of ErrPrefixDto.

This method is identical in function to ErrPrefixDto.SetEPref(). The only difference is that this method returns a pointer to the current ErrPrefixDto instance.

The error prefix text is designed to be configured at the beginning of error messages and is most often used to document the thread of code execution by listing the calling sequence for specific functions and methods.

This method is designed to process a single error prefix string passed in input parameter 'ErrPrefixDto'. If this string contains multiple error prefixes, use method 'ErrPrefixDto.SetEPrefOld()'.

Be advised: The 'X' methods always return a pointer to current, modified, ErrPrefixDto instance.

----------------------------------------------------------------

Input Parameters 

newErrPrefix        string
   - The new error prefix represents typically identifies
     the function or method which is currently executing. This
     information is used to document source code execution flow
     in error messages.

     This new error prefix will be added to the internal list
     of error prefixes maintained by this ErrPrefixDto
     instance.

-----------------------------------------------------------------

Return Values 

*ErrPrefixDto
   - Returns a pointer to the current ErrPrefixDto instance

func (*ErrPrefixDto) XEPrefCtx added in v1.1.0 

func (ePrefDto *ErrPrefixDto) XEPrefCtx(
	newErrPrefix string,
	newErrContext string) *ErrPrefixDto

XEPrefCtx - Adds an error prefix and an error context string to the list of previous error prefix/context information.

This method is identical in function to ErrPrefixDto.SetEPrefCtx(). The only difference is that this method returns a pointer to the current ErrPrefixDto instance.

Error prefix text is designed to be configured at the beginning of error messages and is most often used to document the thread of code execution by listing the calling sequence for a specific list of functions and methods.

The error context string is designed to provide additional information about the function or method identified by the associated error prefix string. Typical context information might include variable names, variable values and additional details on function execution.

Be advised: The 'X' methods always return a pointer to current, modified, ErrPrefixDto instance.

----------------------------------------------------------------

Input Parameters 

newErrPrefix        string
   - The new error prefix represents typically identifies
     the function or method which is currently executing. This
     information is used to document source code execution flow
     in error messages.

     This method is designed to process a single new error prefix
     string. To process a collection of error prefix strings, see
     method 'ErrPrefixDto.SetEPrefOld()'.

newErrContext       string
   - This is the error context information associated with the
     new error prefix ('newErrPrefix'). This parameter is
     optional and will accept an empty string.

-----------------------------------------------------------------

Return Values 

*ErrPrefixDto
   - Returns a pointer to the current ErrPrefixDto instance.

func (*ErrPrefixDto) XEPrefOld added in v1.1.0 

func (ePrefDto *ErrPrefixDto) XEPrefOld(
	oldErrPrefix string) *ErrPrefixDto

XEPrefOld - Deletes the current error prefix information and initializes this ErrPrefixDto instance with an old or preexisting error prefix string. This error prefix string input parameter typically includes one or more error prefix elements and may also include associated error context elements. This string will be parsed and into individual error prefix and error context components and stored internally in the current ErrPrefixDto instance.

This method is identical in function to ErrPrefixDto.SetEPrefOld(). The only difference is that this method returns a pointer to the current ErrPrefixDto instance.

Error prefix text is designed to be configured at the beginning of error messages and is most often used to document the thread of code execution by listing the calling sequence for a specific list of functions and methods.

The error context string is designed to provide additional information about the function or method identified by the associated error prefix string. Typical context information might include variable names, variable values and additional details on function execution.

Be advised: The 'X' methods always return a pointer to current, modified, ErrPrefixDto instance.

IMPORTANT All existing error prefix and error context information in this ErrPrefixDto instance will be overwritten and deleted.

----------------------------------------------------------------

Input Parameters 

oldErrPrefix        string
   - This includes the previous or preexisting error prefix
     string. This string will be parsed into error prefix
     and error context components and stored in the current
     ErrPrefixDto instance.

     This string should consist of a series of error prefix
     strings. Error prefixes should be delimited by either a
     new line character ('\n') or the in-line delimiter string,
     " - ".

     If this string contains associated error context strings
     as well, they should be delimited with either a new line
     delimiter string, "\n :  " or an in-line delimiter string,
     " : ".

-----------------------------------------------------------------

Return Values 

*ErrPrefixDto
   - Returns a pointer to the current ErrPrefixDto instance

func (*ErrPrefixDto) XSetFromStrings added in v1.6.0 

func (ePrefDto *ErrPrefixDto) XSetFromStrings(
	oldErrPrefix string,
	newErrPrefix string,
	newErrContext string,
	inputStrDelimiters ErrPrefixDelimiters,
	outputStrDelimiters ErrPrefixDelimiters,
	ePrefix string) (*ErrPrefixDto, error)

XSetFromStrings - Receives a series of string parameters and proceeds to delete and overwrite the existing error prefix information contained in the current ErrPrefixDto instance. The string parameters include error prefix and associated error context information.

In addition, this method allows the user to specify both the input and output string delimiters. Input string delimiters are used to parse the Old Error Prefix string, the New Error Prefix string and the associated New Error Context string. The output string delimiters will be used to parse and format presentation error prefix information returned by methods: 

ErrPrefixDto.String()
ErrPrefixDto.StrMaxLineLen()

Error prefix text is designed to be configured at the beginning of error messages and is most often used to document the thread of code execution by listing the calling sequence for a specific list of functions and methods.

The error context string is designed to provide additional information about the function or method identified by the associated error prefix string. Typical context information might include variable names, variable values and additional details on function execution.

If all three of the input parameter strings are passed as empty strings, this method will simply create an unpopulated or empty instance of ErrPrefixDto configured with the input and output string delimiters passed by the calling function.

If either of the input or output string delimiter objects are judged as invalid, this method will return an error.

Be advised: The 'X' methods always return a pointer to current, modified, ErrPrefixDto instance.

IMPORTANT All existing error prefix and error context information in this ErrPrefixDto instance will be overwritten and deleted.

----------------------------------------------------------------

Input Parameters 

oldErrPrefix        string
   - This includes the previous or preexisting error prefix
     string which will encapsulate one or more error prefix
     elements. This string will be parsed into error prefix and
     error context components and stored in the returned
     ErrPrefixDto instance.

     This string will be parsed for error prefix and associated
     error context information based on the input string
     delimiters contained in input parameter,
     'inputStrDelimiters'.

     If this string contains associated error context strings
     as well, they will also be parsed using the same input
     string delimiters.

     This parameter is optional and will accept an empty string.

newErrPrefix               string
   - The new error prefix string typically identifies the
     function or method which is currently executing. This
     information is used to document source code execution flow
     in error messages.

     This parameter is optional and will accept an empty string.

newErrContext              string
   - This is the error context information associated with the
     new error prefix string ('newErrPrefix').

     This parameter is optional and will accept an empty string.

inputStrDelimiters         ErrPrefixDelimiters
   - Sets the string delimiters used by the current
     ErrPrefixDto instance when receiving and parsing raw
     strings containing error prefix information. Such strings
     are parsed in order to extract error prefix information
     for storage in the error prefix collection maintained by
     the current ErrPrefixDto instance.

     If input string delimiters were not directly configured
     by the user, the system default input string delimiters
     will be applied.

     The system default input string delimiters are listed as
     follows:

       New Line Error Prefix Delimiter = "\n"
       In-Line Error Prefix Delimiter  = " - "
       New Line Error Context Delimiter = "\n :  "
       In-Line Error Context Delimiter = " : "

       To monitor input string delimiters, use method:
           ErrPrefixDto.GetInputStringDelimiters()

outputStrDelimiters        ErrPrefixDelimiters
   - Sets the string delimiters used by the current
     ErrPrefixDto instance to format error prefix strings
     returned by methods:
            ErrPrefixDto.String()
            ErrPrefixDto.StrMaxLineLen()

     If the input parameter, 'outputStrDelimiters', is invalid,
     this/ method will return an error.

     If output string delimiters are not directly configured by
     the user, the default output string delimiters will be
     applied.

     The default output string delimiters are listed as
     follows:

       New Line Error Prefix Delimiter = "\n"
       In-Line Error Prefix Delimiter  = " - "
       New Line Error Context Delimiter = "\n :  "
       In-Line Error Context Delimiter = " : "

     To monitor output string delimiters, use method:
       ErrPrefixDto.GetOutputStringDelimiters()

ePrefix                    string
   - This is an error prefix which is included in all returned
     error messages returned by this method. Usually, it
     contains the names of the calling method or methods.

     Note: Be sure to leave a space at the end of 'eMsg'.
     This parameter is optional.

------------------------------------------------------------------------

Return Values 

*ErrPrefixDto
   - Returns a pointer to the current, modified ErrPrefixDto
     instance.

error
   - If this method completes successfully, the returned error Type
     is set to 'nil'. If errors are encountered during processing,
     the returned error Type will encapsulate an error message.
     Note that this error message will incorporate the method
     chain and text passed by input parameter, 'ePrefix'.

------------------------------------------------------------------------

Usage Examples 

ePDto2 := ErrPrefixDto{}
var err error

 ePDto2,
    err = ePDto2.
      XSetFromStrings(
        initialStr,
        newErrPrefix,
        newErrCtx,
        outputDelimiters,
        outputDelimiters,
        funcName)

---------------------------------------
var ePDto2 *ErrPrefixDto
var err error

ePDto2,
err = ErrPrefixDto{}.Ptr().
      XSetFromStrings(
        initialStr,
        newErrPrefix,
        newErrCtx,
        outputDelimiters,
        outputDelimiters,
        funcName)

func (*ErrPrefixDto) ZCtx added in v1.4.0 

func (ePrefDto *ErrPrefixDto) ZCtx(
	newErrContext string) ErrPrefixDto

ZCtx - Sets or resets the error context for the last error prefix. This operation either adds, or replaces, the error context string associated with the last error prefix the current list of error prefixes maintained by this instance.

This method is identical in function to ErrPrefixDto.SetCtx(). The only difference is that this method returns a deep copy of the current ErrPrefixDto instance.

If the last error prefix already has an error context string, it will be replaced by input parameter, 'newErrContext'.

If the last error prefix does NOT have an associated error context, this new error context string will be associated with that error prefix.

If the internal list of error prefixes is currently empty, this method will take no action and exit.

If the input parameter string 'newErrContext' is 'empty' (zero length string), this method will delete the last error context associated with the last error prefix in the error prefix collection.

This method returns a deep copy of the current ErrPrefixDto instance after it is updated with new error context information. This copy of ErrPrefixDto returned by value.

----------------------------------------------------------------

Input Parameters 

newErrContext       string
   - This string holds the new error context information. If
     the last error prefix in internal storage already has an
     associated error context, that context will be deleted and
     replaced by 'newErrContext'. If, however, the last error
     prefix does NOT have an associated error context, this
     'newErrContext' string will be added and associated with
     that last error prefix.

     If this string is 'empty' (zero length string), this
     method will delete the last error context associated with
     the last error prefix in the error prefix collection.

-----------------------------------------------------------------

Return Values 

ErrPrefixDto
   - This method returns a deep copy of the current
     ErrPrefixDto instance after it is updated with new error
     context information. This copy is returned by value.

func (*ErrPrefixDto) ZCtxEmpty added in v1.4.0 

func (ePrefDto *ErrPrefixDto) ZCtxEmpty() ErrPrefixDto

ZCtxEmpty - Deletes the last error context for the last error prefix in this instance of ErrPrefixDto.

This method returns a deep copy of the current ErrPrefixDto instance after it is updated with the deletion of the last error context. This copy is returned by value.

----------------------------------------------------------------

Input Parameters 

--- NONE ---

-----------------------------------------------------------------

Return Values 

ErrPrefixDto
   - This method returns a deep copy of the current
     ErrPrefixDto instance after it is updated with the
     deletion of the last error context. This copy is returned
     by value.

func (*ErrPrefixDto) ZEPref added in v1.4.0 

func (ePrefDto *ErrPrefixDto) ZEPref(
	newErrPrefix string) ErrPrefixDto

ZEPref - Adds an error prefix string to the list of previous error prefix strings maintained by this instance of ErrPrefixDto.

This method is identical in function to ErrPrefixDto.SetEPref(). The only difference is that this method returns an ErrPrefixDto instance by value.

The error prefix text is designed to be configured at the beginning of error messages and is most often used to document the thread of code execution by listing the calling sequence for specific functions and methods.

This method is designed to process a single error prefix string passed in input parameter 'ErrPrefixDto'. If this string contains multiple error prefixes, use method 'ErrPrefixDto.SetEPrefOld()'.

This method returns a deep copy of the current ErrPrefixDto instance after it is updated with new error prefix information. This copy of ErrPrefixDto is returned by value.

----------------------------------------------------------------

Input Parameters 

newErrPrefix        string
   - The new error prefix represents typically identifies
     the function or method which is currently executing. This
     information is used to document source code execution flow
     in error messages.

     This new error prefix will be added to the internal list
     of error prefixes maintained by this ErrPrefixDto
     instance.

-----------------------------------------------------------------

Return Values 

ErrPrefixDto
   - This method returns a deep copy of the current
     ErrPrefixDto instance after it is updated with
     new error prefix information. This copy of
     ErrPrefixDto is returned by value.

func (*ErrPrefixDto) ZEPrefCtx added in v1.4.0 

func (ePrefDto *ErrPrefixDto) ZEPrefCtx(
	newErrPrefix string,
	newErrContext string) ErrPrefixDto

ZEPrefCtx - Adds an error prefix and an error context string to the list of previous error prefix/context information.

This method is identical in function to ErrPrefixDto.SetEPrefCtx(). The only difference is that this method returns an ErrPrefixDto instance by value.

Error prefix text is designed to be configured at the beginning of error messages and is most often used to document the thread of code execution by listing the calling sequence for a specific list of functions and methods.

The error context string is designed to provide additional information about the function or method identified by the associated error prefix string. Typical context information might include variable names, variable values and additional details on function execution.

This method returns a deep copy of the current ErrPrefixDto instance after it is updated with new error prefix and error context information. This copy of ErrPrefixDto is returned by value.

----------------------------------------------------------------

Input Parameters 

newErrPrefix        string
   - The new error prefix represents typically identifies
     the function or method which is currently executing. This
     information is used to document source code execution flow
     in error messages.

     This method is designed to process a single new error prefix
     string. To process a collection of error prefix strings, see
     method 'ErrPrefixDto.SetEPrefOld()'.

newErrContext       string
   - This is the error context information associated with the
     new error prefix ('newErrPrefix'). This parameter is
     optional and will accept an empty string.

-----------------------------------------------------------------

Return Values 

ErrPrefixDto
   - This method returns a deep copy of the current
     ErrPrefixDto instance after it is updated with new error
     prefix and error context information. This copy of
     ErrPrefixDto is returned by value.

func (*ErrPrefixDto) ZEPrefOld added in v1.4.0 

func (ePrefDto *ErrPrefixDto) ZEPrefOld(
	oldErrPrefix string) ErrPrefixDto

ZEPrefOld - Deletes the current error prefix information and initializes this ErrPrefixDto instance with an old or preexisting error prefix string. This error prefix string input parameter typically includes one or more error prefix elements and may also include associated error context elements. This string will be parsed and into individual error prefix and error context components and stored internally in the current ErrPrefixDto instance.

This method is identical in function to ErrPrefixDto.SetEPrefOld(). The only difference is that this method returns an ErrPrefixDto instance by value.

Error prefix text is designed to be configured at the beginning of error messages and is most often used to document the thread of code execution by listing the calling sequence for a specific list of functions and methods.

The error context string is designed to provide additional information about the function or method identified by the associated error prefix string. Typical context information might include variable names, variable values and additional details on function execution.

This method returns a deep copy of the current ErrPrefixDto instance after it is updated with preexisting error prefix information. This copy of ErrPrefixDto is returned by value.

IMPORTANT All existing error prefix and error context information in this ErrPrefixDto instance will be overwritten and deleted.

----------------------------------------------------------------

Input Parameters 

oldErrPrefix        string
   - This includes the previous or preexisting error prefix
     string. This string will be parsed into error prefix
     and error context components and stored in the current
     ErrPrefixDto instance.

     This string should consist of a series of error prefix
     strings. Error prefixes should be delimited by either a
     new line character ('\n') or the in-line delimiter string,
     " - ".

     If this string contains associated error context strings
     as well, they should be delimited with either a new line
     delimiter string, "\n :  " or an in-line delimiter string,
     " : ".

-----------------------------------------------------------------

Return Values 

ErrPrefixDto
   - This method returns a deep copy of the current
     ErrPrefixDto instance after it is updated with preexisting
     error prefix information. This copy of ErrPrefixDto is
     returned by value.

type ErrorPrefixInfo 

type ErrorPrefixInfo struct {
	// contains filtered or unexported fields
}

func (*ErrorPrefixInfo) CopyIn 

func (errorPrefixInfo *ErrorPrefixInfo) CopyIn(
	inComingErrPrefixInfo *ErrorPrefixInfo,
	ePrefix string) error

CopyIn - Copies the data fields from an incoming instance of ErrorPrefixInfo ('inComingErrPrefixInfo') to the data fields of the current ErrorPrefixInfo instance ('errorPrefixInfo').

If 'inComingErrPrefixInfo' is judged to be invalid, this method will return an error.

All of the data fields in current ErrorPrefixInfo instance ('errorPrefixInfo') will be modified and overwritten.

----------------------------------------------------------------

Input Parameters 

inComingErrPrefixInfo      *ErrorPrefixInfo
   - A pointer to an instance of ErrorPrefixInfo. This method
     will NOT change the values of internal member variables
     contained in this instance.

     All data values in this ErrorPrefixInfo instance will be
     copied to current ErrorPrefixInfo instance
     ('errorPrefixInfo').

     If this ErrorPrefixInfo instance proves to be invalid, an
     error will be returned.

ePrefix                    string
   - This is an error prefix which is included in all returned
     error messages. Usually, it contains the names of the calling
     method or methods. Note: Be sure to leave a space at the end
     of 'ePrefix'.

------------------------------------------------------------------------

Return Values 

err                        error
   - If this method completes successfully, the returned error Type
     is set to 'nil'. If errors are encountered during processing,
     the returned error Type will encapsulate an error message.
     Note that this error message will incorporate the method
     chain and text passed by input parameter, 'ePrefix'.

func (*ErrorPrefixInfo) CopyOut 

func (errorPrefixInfo *ErrorPrefixInfo) CopyOut(
	ePrefix string) (
	ErrorPrefixInfo,
	error)

CopyOut - Creates a deep copy of the data fields contained in the current ErrorPrefixInfo instance, and returns that data as a new instance of ErrorPrefixInfo.

------------------------------------------------------------------------

Input Parameters 

ePrefix             string
   - This is an error prefix which is included in all returned
     error messages. Usually, it contains the names of the calling
     method or methods. Note: Be sure to leave a space at the end
     of 'ePrefix'.

------------------------------------------------------------------------

Return Values 

ErrorPrefixInfo
   - If this method completes successfully, a deep copy of the
     current ErrorPrefixInfo instance will be returned through
     this parameter as a completely new instance of
     ErrorPrefixInfo.

error
   - If this method completes successfully, the returned error Type
     is set to 'nil'. If errors are encountered during processing,
     the returned error Type will encapsulate an error message.
     Note that this error message will incorporate the method
     chain and text passed by input parameter, 'ePrefix'. The
     'ePrefix' text will be prefixed to the beginning of the returned
     error message.

func (*ErrorPrefixInfo) Empty added in v1.5.0 

func (errorPrefixInfo *ErrorPrefixInfo) Empty()

Empty - Resets all internal member variables to their zero values.

func (*ErrorPrefixInfo) Equal 

func (errorPrefixInfo *ErrorPrefixInfo) Equal(
	ePrefixInfo02 *ErrorPrefixInfo) bool

Equal - Returns a boolean flag signaling whether the data values contained in the current ErrorPrefixInfo instance are equal to to those contained in input parameter, 'ePrefixInfo02'

------------------------------------------------------------------------

Input Parameters 

ePrefixInfo02       *ErrorPrefixInfo
   - A pointer to an instance of ErrorPrefixInfo. The data
     values contained in this instance will be compared to
     those contained in the current ErrorPrefixInfo instance
     (errorPrefixInfo) to determine equality.

------------------------------------------------------------------------

Return Values 

bool
   - A boolean flag signaling whether the data values contained
     in the current ErrorPrefixInfo instance are equal to those
     contained in input parameter 'ePrefixInfo02'. If the data
     values are equal in all respects, this returned boolean
     value will be set to 'true'.

func (*ErrorPrefixInfo) GetErrContextStr 

func (errorPrefixInfo *ErrorPrefixInfo) GetErrContextStr() string

GetErrContextStr - Returns the Error Context String.

func (*ErrorPrefixInfo) GetErrPrefixHasContextStr 

func (errorPrefixInfo *ErrorPrefixInfo) GetErrPrefixHasContextStr() bool

GetErrPrefixHasContextStr - Returns a boolean flag signaling whether the Error Prefix String defined in this ErrorPrefixInfo instance has an associated Error Context string.

If the returned boolean value is 'true' is signals that this Error Prefix has an associated Error Context String.

func (*ErrorPrefixInfo) GetErrPrefixStr 

func (errorPrefixInfo *ErrorPrefixInfo) GetErrPrefixStr() string

GetErrPrefixStr - Returns the Error Prefix String.

func (*ErrorPrefixInfo) GetIsFirstIndex 

func (errorPrefixInfo *ErrorPrefixInfo) GetIsFirstIndex() bool

GetIsFirstIndex - Returns a boolean flag signaling whether the current ErrorPrefixInfo instance is the First element in an array.

If the returned boolean value is 'true', it signals that this ErrorPrefixInfo object is the First element in an array.

func (*ErrorPrefixInfo) GetIsLastIndex 

func (errorPrefixInfo *ErrorPrefixInfo) GetIsLastIndex() bool

GetIsLastIndex - Returns a boolean flag signaling whether the current ErrorPrefixInfo instance is the last element in an array.

If the returned boolean value is 'true', it signals that this ErrorPrefixInfo object is the last element in an array.

func (*ErrorPrefixInfo) GetIsPopulated 

func (errorPrefixInfo *ErrorPrefixInfo) GetIsPopulated() bool

GetIsPopulated - Returns a boolean flag signaling whether the current ErrorPrefixInfo instance is populated with valid data.

If the returned boolean value is 'true', it signals that this ErrorPrefixInfo object IS POPULATED with valid data.

func (*ErrorPrefixInfo) GetLengthErrContextStr 

func (errorPrefixInfo *ErrorPrefixInfo) GetLengthErrContextStr() uint

GetLengthErrContextStr - Returns the number of characters in the Error Context String. This is also known as the string length and it is returned as a type unsigned integer.

func (*ErrorPrefixInfo) GetLengthErrPrefixStr 

func (errorPrefixInfo *ErrorPrefixInfo) GetLengthErrPrefixStr() uint

GetLengthErrPrefixStr - Returns the number of characters in the Error Prefix String. This also known as the string length and it is returned as a type unsigned integer.

func (*ErrorPrefixInfo) IsValidInstance 

func (errorPrefixInfo *ErrorPrefixInfo) IsValidInstance() (
	isValid bool)

IsValidInstance - Returns a boolean flag signaling whether the current ErrorPrefixInfo instance is invalid.

If the returned boolean value is 'true', it signals that the current ErrorPrefixInfo instance is valid and populated with data.

If the boolean value is 'false', it signals that the current ErrorPrefixInfo instance is invalid.

----------------------------------------------------------------

Input Parameters 

--- NONE ---

-----------------------------------------------------------------

Return Values 

isValid             bool
   - If the current ErrorPrefixInfo instance, 'errorPrefixInfo',
     contains invalid data, this boolean value is set to 'false'.

     If the current ErrorPrefixInfo instance, 'errorPrefixInfo',
     is valid, this boolean value is set to 'true'.

func (*ErrorPrefixInfo) IsValidInstanceError 

func (errorPrefixInfo *ErrorPrefixInfo) IsValidInstanceError(
	ePrefix string) error

IsValidInstanceError - Returns an error object signaling whether the current ErrorPrefixInfo instance is invalid.

If the returned error value is 'nil', it signals that the current ErrorPrefixInfo instance is valid and populated with data.

If the returned error value is NOT 'nil', it signals that the current ErrorPrefixInfo is invalid. In this case, the error object will contain an appropriate error message.

----------------------------------------------------------------

Input Parameters 

ePrefix             string
   - This is an error prefix which is included in all returned
     error messages. Usually, it contains the names of the calling
     method or methods. Be sure to leave a space at the end of
     'ePrefix'.

-----------------------------------------------------------------

Return Values 

error
   - If the current ErrorPrefixInfo instance, 'errorPrefixInfo',
     contains invalid data, a detailed error message will be
     returned identifying the invalid data item.

     If the current ErrorPrefixInfo instance, 'errorPrefixInfo',
     is valid, this error parameter will be set to 'nil'.

func (ErrorPrefixInfo) New 

func (errorPrefixInfo ErrorPrefixInfo) New() ErrorPrefixInfo

New - Creates and returns a new instance of type, 'ErrorPrefixInfo'.

func (ErrorPrefixInfo) Ptr 

func (errorPrefixInfo ErrorPrefixInfo) Ptr() *ErrorPrefixInfo

Ptr - Returns a pointer to a new instance of ErrorPrefixInfo.

func (*ErrorPrefixInfo) SetErrContextStr 

func (errorPrefixInfo *ErrorPrefixInfo) SetErrContextStr(
	errContext string)

SetErrContextStr - Sets the Error Context String value.

In addition, this method also calculates and set the value of length or number of characters contained in the Error Context String.

func (*ErrorPrefixInfo) SetErrPrefixHasContext 

func (errorPrefixInfo *ErrorPrefixInfo) SetErrPrefixHasContext(
	errPrefixHasContextStr bool)

SetErrPrefixHasContext - Sets an internal boolean flag specifying whether the Error Prefix String for this ErrorPrefixInfo instance has an associated Error Context String.

If this boolean flag is set to 'true' is signals that this Error Prefix String has an associated Error Context String.

func (*ErrorPrefixInfo) SetErrPrefixStr 

func (errorPrefixInfo *ErrorPrefixInfo) SetErrPrefixStr(
	errPrefix string)

SetErrPrefixStr - Sets the value of the error prefix string.

In addition, this method also calculates and set the value of length or number of characters contained in the error prefix string.

func (*ErrorPrefixInfo) SetIsFirstIndex 

func (errorPrefixInfo *ErrorPrefixInfo) SetIsFirstIndex(isFirstIndex bool)

SetIsFirstIndex - Sets an internal flag designating whether the current ErrorPrefixInfo instance is the first element in an array of ErrorPrefixInfo objects.

If the input parameter 'isFirstIndex' is 'true', it signals that this ErrorPrefixInfo object is the FIRST element in an array.

func (*ErrorPrefixInfo) SetIsLastIndex 

func (errorPrefixInfo *ErrorPrefixInfo) SetIsLastIndex(isLastIdx bool)

SetIsLastIndex - Sets an internal flag designating whether the current ErrorPrefixInfo instance is the last element in an array of ErrorPrefixInfo objects.

If the input parameter 'isLastIdx' is 'true', it signals that this ErrorPrefixInfo object is the LAST element in an array.

func (*ErrorPrefixInfo) SetIsPopulated 

func (errorPrefixInfo *ErrorPrefixInfo) SetIsPopulated(
	isPopulated bool)

SetIsPopulated - Sets an internal flag indicating whether the current ErrorPrefixInfo instance is, or is NOT, populated with valid data.

If input parameter 'isPopulated' is set to 'true' it signals this instance of ErrorPrefixInfo is populated with valid data.

type IBasicErrorPrefix added in v1.5.0 

type IBasicErrorPrefix interface {
	GetEPrefStrings() [][2]string
}

type IBuilderErrorPrefix added in v1.5.0 

type IBuilderErrorPrefix interface {
	GetEPrefStrings() [][2]string

	SetEPrefStrings(twoDStrArray [][2]string)

	String() string
}

type IErrorPrefix added in v1.3.0 

type IErrorPrefix interface {
	GetEPrefStrings() [][2]string

	GetEPrefCollectionLen() int

	GetIsLastLineTerminatedWithNewLine() bool

	SetCtx(newErrContext string)

	SetCtxEmpty()

	SetEPref(newErrPrefix string)

	SetEPrefCtx(newErrPrefix string, newErrContext string)

	SetEPrefOld(oldErrPrefix string)

	SetEPrefStrings(twoDStrArray [][2]string)

	SetMaxTextLineLen(maxErrPrefixTextLineLength int)

	SetIsLastLineTermWithNewLine(isLastLineTerminatedWithNewLine bool)

	String() string
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.